From fcb400328d6584948d4099b603919b837da8f0e5 Mon Sep 17 00:00:00 2001
From: charliecloudberry <cloudberrycharlie@gmail.com>
Date: Thu, 6 Aug 2026 02:27:36 +0200
Subject: [PATCH 01/16] support django template files
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

templates get completions, go-to-definition and semantic highlighting,
all of it joined to the project's own django definitions rather than to a
grammar: `{{ book.author. }}` completes model fields because some view
wrote `render(request, "post.html", {"book": book})` and the type checker
knows what that `book` is.

the template front end is new — a lexer for the three constructs, and an
index that recovers block nesting from the tags that impose it, since the
delimiters do not. everything else is a join to the python side: the
`templatetags` modules a `{% load %}` names, the `path(…, name=…)` a
`{% url %}` reverses, the `render()` call a `{{ variable }}` comes from.

the server recognises a template from the editor's language id, or from
the path when the editor just says `html`. a template's `File` is
interned so its source can be read, but it never enters the project's
open-file set, so the type checker is never handed an html file.

the semantic token legend grows two types and a modifier. both are
appended: a token type's position in the enum is the index the wire
format sends, so inserting would silently recolour every python file.
---
 crates/ty_ide/src/django_template.rs          |  232 ++++
 crates/ty_ide/src/django_template/builtins.rs |  769 ++++++++++++
 .../ty_ide/src/django_template/completion.rs  | 1084 +++++++++++++++++
 crates/ty_ide/src/django_template/goto.rs     |  492 ++++++++
 crates/ty_ide/src/django_template/index.rs    | 1016 +++++++++++++++
 crates/ty_ide/src/django_template/lexer.rs    |  917 ++++++++++++++
 crates/ty_ide/src/django_template/project.rs  |  740 +++++++++++
 crates/ty_ide/src/django_template/resolve.rs  |  222 ++++
 .../src/django_template/semantic_tokens.rs    |  357 ++++++
 crates/ty_ide/src/lib.rs                      |    8 +-
 crates/ty_ide/src/semantic_tokens.rs          |   28 +-
 .../src/types/ide_support.rs                  |   10 +
 crates/ty_server/src/capabilities.rs          |   16 +-
 .../ty_server/src/document/text_document.rs   |   36 +-
 .../ty_server/src/server/api/diagnostics.rs   |    8 +
 .../src/server/api/notifications/did_open.rs  |    2 +-
 .../api/notifications/did_open_notebook.rs    |    2 +-
 .../src/server/api/requests/completion.rs     |   90 ++
 .../server/api/requests/goto_definition.rs    |   10 +-
 .../server/api/requests/semantic_tokens.rs    |    4 +-
 .../api/requests/semantic_tokens_range.rs     |    1 +
 .../src/server/api/semantic_tokens.rs         |   14 +-
 crates/ty_server/src/session.rs               |   47 +-
 crates/ty_server/src/session/index.rs         |    2 +-
 crates/ty_server/src/system.rs                |    4 +-
 .../ty_server/tests/e2e/django_templates.rs   |  259 ++++
 crates/ty_server/tests/e2e/main.rs            |   14 +-
 .../e2e__initialize__initialization.snap      |   12 +-
 ...ialize__initialization_with_workspace.snap |   12 +-
 crates/ty_wasm/src/lib.rs                     |    4 +
 .../frameworks/django-templates.md            |  118 ++
 docs/basedpython/frameworks/django.md         |    5 +
 zensical.toml                                 |    1 +
 33 files changed, 6501 insertions(+), 35 deletions(-)
 create mode 100644 crates/ty_ide/src/django_template.rs
 create mode 100644 crates/ty_ide/src/django_template/builtins.rs
 create mode 100644 crates/ty_ide/src/django_template/completion.rs
 create mode 100644 crates/ty_ide/src/django_template/goto.rs
 create mode 100644 crates/ty_ide/src/django_template/index.rs
 create mode 100644 crates/ty_ide/src/django_template/lexer.rs
 create mode 100644 crates/ty_ide/src/django_template/project.rs
 create mode 100644 crates/ty_ide/src/django_template/resolve.rs
 create mode 100644 crates/ty_ide/src/django_template/semantic_tokens.rs
 create mode 100644 crates/ty_server/tests/e2e/django_templates.rs
 create mode 100644 docs/basedpython/frameworks/django-templates.md

diff --git a/crates/ty_ide/src/django_template.rs b/crates/ty_ide/src/django_template.rs
new file mode 100644
index 0000000000..8f20052d06
--- /dev/null
+++ b/crates/ty_ide/src/django_template.rs
@@ -0,0 +1,232 @@
+//! ide support for django template files
+//!
+//! django templates are not python, so none of the machinery the rest of this
+//! crate is built on — the parser, the semantic index, type inference — applies
+//! to them. what *is* shared is the project: a template's variables come from
+//! the view that renders it, its `{% url %}` names come from the project's url
+//! configuration, and its custom tags and filters come from the project's
+//! `templatetags` modules. so this module owns a small template front end of its
+//! own ([`lexer`], [`index`]) and spends the rest of its effort joining it to the
+//! python side ([`project`]).
+
+mod builtins;
+mod completion;
+mod goto;
+mod index;
+mod lexer;
+mod project;
+mod resolve;
+mod semantic_tokens;
+
+pub use completion::{TemplateCompletion, TemplateEdit};
+
+use ruff_db::files::File;
+use ruff_db::source::source_text;
+use ruff_db::system::SystemPath;
+use ruff_text_size::{TextRange, TextSize};
+use ty_project::Db;
+
+use crate::semantic_tokens::SemanticTokens;
+use crate::{NavigationTargets, RangedValue};
+
+use index::TemplateIndex;
+
+/// the file extensions a django template is conventionally written with
+///
+/// django itself puts no constraint on the extension — the template loader takes
+/// whatever path it is given — so this list only decides what the server will
+/// *offer* template support for when the editor hasn't already told it the file
+/// is a template.
+const TEMPLATE_EXTENSIONS: &[&str] = &["html", "htm", "txt", "xml", "django", "dj", "jinja"];
+
+/// the directory name django's app-directories loader looks in
+const TEMPLATE_DIRECTORY: &str = "templates";
+
+/// whether `path` looks like a django template
+///
+/// an editor that knows the file's language (vs code's `django-html`, vim's
+/// `htmldjango`) tells the server directly and this is never consulted. it is
+/// the fallback for the much more common case of a `.html` file that the editor
+/// reports as plain html, and it deliberately requires the file to be *inside* a
+/// `templates` directory so that ordinary html in a project is left alone.
+pub fn is_django_template_path(path: &SystemPath) -> bool {
+    let has_template_extension = path
+        .extension()
+        .is_some_and(|extension| TEMPLATE_EXTENSIONS.contains(&extension));
+
+    has_template_extension
+        && path
+            .ancestors()
+            .any(|ancestor| ancestor.file_name() == Some(TEMPLATE_DIRECTORY))
+}
+
+/// the index of `file`, parsed as a django template
+///
+/// the query is tracked so that the several ide features that need it — the
+/// completions, the semantic tokens, goto — parse each template once per edit
+/// rather than once per request.
+#[salsa::tracked(returns(ref), heap_size=ruff_memory_usage::heap_size)]
+fn template_index(db: &dyn Db, file: File) -> TemplateIndex {
+    TemplateIndex::from_source(source_text(db, file).as_str())
+}
+
+/// the semantic tokens of `file`, read as a django template
+///
+/// `range` restricts the result to the tokens it touches, for the ranged
+/// semantic-tokens request.
+pub fn django_template_semantic_tokens(
+    db: &dyn Db,
+    file: File,
+    range: Option<TextRange>,
+) -> SemanticTokens {
+    let source = source_text(db, file);
+    SemanticTokens::new(semantic_tokens::semantic_tokens(
+        template_index(db, file),
+        source.as_str(),
+        range,
+    ))
+}
+
+/// where the name at `offset` of `file` is defined, read as a django template
+pub fn django_template_goto_definition(
+    db: &dyn Db,
+    file: File,
+    offset: TextSize,
+) -> Option<RangedValue<NavigationTargets>> {
+    let source = source_text(db, file);
+    goto::goto_definition(db, file, template_index(db, file), source.as_str(), offset)
+}
+
+/// the completions for `offset` in `file`, read as a django template
+pub fn django_template_completions(
+    db: &dyn Db,
+    file: File,
+    offset: TextSize,
+) -> Vec<TemplateCompletion> {
+    let source = source_text(db, file);
+    completion::completions(db, file, template_index(db, file), source.as_str(), offset)
+}
+
+#[cfg(test)]
+pub(crate) mod tests {
+    use ruff_db::files::{File, system_path_to_file};
+    use ruff_db::system::{DbWithWritableSystem, SystemPath, SystemPathBuf};
+    use ruff_python_ast::PythonVersion;
+    use ruff_python_trivia::textwrap::dedent;
+    use ruff_text_size::TextSize;
+    use ty_project::{ProjectMetadata, TestDb};
+
+    use super::{
+        django_template_completions, django_template_goto_definition, is_django_template_path,
+    };
+
+    /// a project whose files are written out, with the cursor marked by
+    /// `<CURSOR>` in exactly one of them
+    pub(crate) struct TemplateTest {
+        pub(crate) db: TestDb,
+        pub(crate) file: File,
+        pub(crate) offset: TextSize,
+    }
+
+    impl TemplateTest {
+        /// build a project from `(path, contents)` pairs
+        pub(crate) fn new(sources: &[(&str, &str)]) -> Self {
+            const MARKER: &str = "<CURSOR>";
+
+            let mut db = TestDb::new(ProjectMetadata::new("test", SystemPathBuf::from("/")));
+            db.init_program_with_python_version(PythonVersion::latest_ty())
+                .unwrap();
+
+            let mut cursor = None;
+
+            for (path, contents) in sources {
+                let contents = dedent(contents).into_owned();
+
+                let (contents, offset) = match contents.find(MARKER) {
+                    Some(index) => {
+                        let mut without = contents[..index].to_string();
+                        without.push_str(&contents[index + MARKER.len()..]);
+                        (without, Some(TextSize::try_from(index).unwrap()))
+                    }
+                    None => (contents, None),
+                };
+
+                db.write_file(path, &contents).unwrap();
+                let file = system_path_to_file(&db, path).unwrap();
+
+                if let Some(offset) = offset {
+                    assert!(cursor.is_none(), "more than one `<CURSOR>` marker");
+                    cursor = Some((file, offset));
+                }
+            }
+
+            let (file, offset) = cursor.expect("a source to contain `<CURSOR>`");
+            Self { db, file, offset }
+        }
+
+        /// the labels of the completions at the cursor, in the order offered
+        pub(crate) fn completions(&self) -> Vec<String> {
+            django_template_completions(&self.db, self.file, self.offset)
+                .into_iter()
+                .map(|completion| completion.label)
+                .collect()
+        }
+
+        /// the completions at the cursor, rendered as `label — detail`
+        pub(crate) fn detailed(&self) -> Vec<String> {
+            django_template_completions(&self.db, self.file, self.offset)
+                .into_iter()
+                .map(|completion| match completion.detail {
+                    Some(detail) => format!("{} — {detail}", completion.label),
+                    None => completion.label,
+                })
+                .collect()
+        }
+
+        /// where goto-definition at the cursor lands, as `path:text`
+        pub(crate) fn definitions(&self) -> Vec<String> {
+            let Some(targets) = django_template_goto_definition(&self.db, self.file, self.offset)
+            else {
+                return Vec::new();
+            };
+
+            targets
+                .into_iter()
+                .map(|target| {
+                    let source = ruff_db::source::source_text(&self.db, target.file());
+                    format!(
+                        "{}:{}",
+                        // the memory file system reports the host's separator
+                        target.file().path(&self.db).to_string().replace('\\', "/"),
+                        &source[target.focus_range()]
+                    )
+                })
+                .collect()
+        }
+    }
+
+    #[test]
+    fn a_template_is_an_html_file_under_a_templates_directory() {
+        assert!(is_django_template_path(SystemPath::new(
+            "/app/templates/blog/post.html"
+        )));
+        assert!(is_django_template_path(SystemPath::new(
+            "/templates/base.txt"
+        )));
+    }
+
+    #[test]
+    fn ordinary_html_outside_a_templates_directory_is_not_a_template() {
+        assert!(!is_django_template_path(SystemPath::new(
+            "/app/static/index.html"
+        )));
+        assert!(!is_django_template_path(SystemPath::new("/README.html")));
+    }
+
+    #[test]
+    fn a_python_file_is_never_a_template() {
+        assert!(!is_django_template_path(SystemPath::new(
+            "/app/templates/views.py"
+        )));
+    }
+}
diff --git a/crates/ty_ide/src/django_template/builtins.rs b/crates/ty_ide/src/django_template/builtins.rs
new file mode 100644
index 0000000000..0bee7ac9f8
--- /dev/null
+++ b/crates/ty_ide/src/django_template/builtins.rs
@@ -0,0 +1,769 @@
+//! django's builtin template tags and filters
+//!
+//! these are the ones `django.template.defaulttags`, `django.template.defaultfilters`
+//! and the libraries shipped in `django.templatetags` register. a project's own
+//! tags and filters are discovered from its source instead — see [`super::project`].
+//!
+//! the tables carry the block structure (which tag closes which, and which tags
+//! may appear in between) because the completions and the index both need it: a
+//! `{% for %}` without the knowledge that `{% empty %}` belongs inside it would
+//! either close the block early or never offer `{% empty %}` at all.
+
+/// a builtin template tag
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub(crate) struct Tag {
+    pub(crate) name: &'static str,
+    /// the tag closing the block this one opens, for a block tag
+    pub(crate) closed_by: Option<&'static str>,
+    /// the tags that may appear between this tag and the one that closes it
+    pub(crate) branches: &'static [&'static str],
+    /// the `{% load %}` library providing this tag, or `None` when it is always
+    /// available
+    pub(crate) library: Option<&'static str>,
+    pub(crate) documentation: &'static str,
+}
+
+/// a builtin template filter
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub(crate) struct Filter {
+    pub(crate) name: &'static str,
+    /// the `{% load %}` library providing this filter, or `None` when it is
+    /// always available
+    pub(crate) library: Option<&'static str>,
+    pub(crate) documentation: &'static str,
+}
+
+/// look a builtin tag up by name
+pub(crate) fn tag(name: &str) -> Option<&'static Tag> {
+    TAGS.iter().find(|tag| tag.name == name)
+}
+
+/// look a builtin filter up by name
+pub(crate) fn filter(name: &str) -> Option<&'static Filter> {
+    FILTERS.iter().find(|filter| filter.name == name)
+}
+
+/// the tag closing the block `name` opens, whether `name` is builtin or one of
+/// the project's own block tags
+pub(crate) fn end_tag_for(name: &str) -> Option<&'static str> {
+    tag(name).and_then(|tag| tag.closed_by)
+}
+
+/// the libraries a `{% load %}` can name
+pub(crate) const LIBRARIES: &[&str] = &["cache", "i18n", "l10n", "static", "tz"];
+
+pub(crate) const TAGS: &[Tag] = &[
+    Tag {
+        name: "autoescape",
+        closed_by: Some("endautoescape"),
+        branches: &[],
+        library: None,
+        documentation: "controls html auto-escaping for the enclosed block. takes `on` or `off`.",
+    },
+    Tag {
+        name: "block",
+        closed_by: Some("endblock"),
+        branches: &[],
+        library: None,
+        documentation: "defines a named block a child template can override.",
+    },
+    Tag {
+        name: "comment",
+        closed_by: Some("endcomment"),
+        branches: &[],
+        library: None,
+        documentation: "ignores everything between the tags.",
+    },
+    Tag {
+        name: "csrf_token",
+        closed_by: None,
+        branches: &[],
+        library: None,
+        documentation: "renders the hidden csrf token input. required in every `POST` form.",
+    },
+    Tag {
+        name: "cycle",
+        closed_by: None,
+        branches: &[],
+        library: None,
+        documentation: "emits the next of its arguments each time it is reached.",
+    },
+    Tag {
+        name: "debug",
+        closed_by: None,
+        branches: &[],
+        library: None,
+        documentation: "outputs the whole current context, for debugging.",
+    },
+    Tag {
+        name: "extends",
+        closed_by: None,
+        branches: &[],
+        library: None,
+        documentation: "declares this template a child of another. must be the first tag in the file.",
+    },
+    Tag {
+        name: "filter",
+        closed_by: Some("endfilter"),
+        branches: &[],
+        library: None,
+        documentation: "runs the enclosed block's output through the given filters.",
+    },
+    Tag {
+        name: "firstof",
+        closed_by: None,
+        branches: &[],
+        library: None,
+        documentation: "outputs the first of its arguments that is truthy.",
+    },
+    Tag {
+        name: "for",
+        closed_by: Some("endfor"),
+        branches: &["empty"],
+        library: None,
+        documentation: "loops over each item of a sequence. `{% empty %}` supplies the body for an empty one.",
+    },
+    Tag {
+        name: "if",
+        closed_by: Some("endif"),
+        branches: &["elif", "else"],
+        library: None,
+        documentation: "renders its body when the condition is truthy.",
+    },
+    Tag {
+        name: "ifchanged",
+        closed_by: Some("endifchanged"),
+        branches: &["else"],
+        library: None,
+        documentation: "renders its body only when the value has changed since the last loop iteration.",
+    },
+    Tag {
+        name: "include",
+        closed_by: None,
+        branches: &[],
+        library: None,
+        documentation: "renders another template here, with the current context or a `with` one.",
+    },
+    Tag {
+        name: "load",
+        closed_by: None,
+        branches: &[],
+        library: None,
+        documentation: "loads a template tag library, making its tags and filters available.",
+    },
+    Tag {
+        name: "lorem",
+        closed_by: None,
+        branches: &[],
+        library: None,
+        documentation: "emits placeholder lorem ipsum text.",
+    },
+    Tag {
+        name: "now",
+        closed_by: None,
+        branches: &[],
+        library: None,
+        documentation: "formats the current date and time with the given format string.",
+    },
+    Tag {
+        name: "partial",
+        closed_by: None,
+        branches: &[],
+        library: None,
+        documentation: "renders a fragment defined by a `{% partialdef %}`.",
+    },
+    Tag {
+        name: "partialdef",
+        closed_by: Some("endpartialdef"),
+        branches: &[],
+        library: None,
+        documentation: "defines a named, reusable fragment of this template. `inline` also renders it in place.",
+    },
+    Tag {
+        name: "querystring",
+        closed_by: None,
+        branches: &[],
+        library: None,
+        documentation: "renders a url-encoded query string from the request's, with the given changes applied.",
+    },
+    Tag {
+        name: "regroup",
+        closed_by: None,
+        branches: &[],
+        library: None,
+        documentation: "regroups a list of objects by a common attribute.",
+    },
+    Tag {
+        name: "resetcycle",
+        closed_by: None,
+        branches: &[],
+        library: None,
+        documentation: "restarts a `{% cycle %}` from its first argument.",
+    },
+    Tag {
+        name: "spaceless",
+        closed_by: Some("endspaceless"),
+        branches: &[],
+        library: None,
+        documentation: "strips the whitespace between html tags in its body.",
+    },
+    Tag {
+        name: "templatetag",
+        closed_by: None,
+        branches: &[],
+        library: None,
+        documentation: "outputs one of the template language's own delimiters, such as `openblock`.",
+    },
+    Tag {
+        name: "url",
+        closed_by: None,
+        branches: &[],
+        library: None,
+        documentation: "reverses a named url pattern into its path.",
+    },
+    Tag {
+        name: "verbatim",
+        closed_by: Some("endverbatim"),
+        branches: &[],
+        library: None,
+        documentation: "outputs its body without rendering any template syntax in it.",
+    },
+    Tag {
+        name: "widthratio",
+        closed_by: None,
+        branches: &[],
+        library: None,
+        documentation: "scales a value against a maximum, for bar-chart widths.",
+    },
+    Tag {
+        name: "with",
+        closed_by: Some("endwith"),
+        branches: &[],
+        library: None,
+        documentation: "binds names to values for the enclosed block.",
+    },
+    // `cache`
+    Tag {
+        name: "cache",
+        closed_by: Some("endcache"),
+        branches: &[],
+        library: Some("cache"),
+        documentation: "caches the rendered body for the given number of seconds, keyed by the given name.",
+    },
+    // `i18n`
+    Tag {
+        name: "blocktranslate",
+        closed_by: Some("endblocktranslate"),
+        branches: &["plural"],
+        library: Some("i18n"),
+        documentation: "marks a block of text for translation, with placeholders for variables.",
+    },
+    Tag {
+        name: "blocktrans",
+        closed_by: Some("endblocktrans"),
+        branches: &["plural"],
+        library: Some("i18n"),
+        documentation: "the older spelling of `{% blocktranslate %}`.",
+    },
+    Tag {
+        name: "get_available_languages",
+        closed_by: None,
+        branches: &[],
+        library: Some("i18n"),
+        documentation: "binds the list of configured `(code, name)` language pairs to a variable.",
+    },
+    Tag {
+        name: "get_current_language",
+        closed_by: None,
+        branches: &[],
+        library: Some("i18n"),
+        documentation: "binds the active language's code to a variable.",
+    },
+    Tag {
+        name: "get_current_language_bidi",
+        closed_by: None,
+        branches: &[],
+        library: Some("i18n"),
+        documentation: "binds whether the active language is right-to-left to a variable.",
+    },
+    Tag {
+        name: "get_language_info",
+        closed_by: None,
+        branches: &[],
+        library: Some("i18n"),
+        documentation: "binds a language's name, code and direction to a variable.",
+    },
+    Tag {
+        name: "get_language_info_list",
+        closed_by: None,
+        branches: &[],
+        library: Some("i18n"),
+        documentation: "binds the language info of each of the given codes to a variable.",
+    },
+    Tag {
+        name: "language",
+        closed_by: Some("endlanguage"),
+        branches: &[],
+        library: Some("i18n"),
+        documentation: "renders its body with the given language active.",
+    },
+    Tag {
+        name: "translate",
+        closed_by: None,
+        branches: &[],
+        library: Some("i18n"),
+        documentation: "translates a string literal or variable.",
+    },
+    Tag {
+        name: "trans",
+        closed_by: None,
+        branches: &[],
+        library: Some("i18n"),
+        documentation: "the older spelling of `{% translate %}`.",
+    },
+    // `l10n`
+    Tag {
+        name: "localize",
+        closed_by: Some("endlocalize"),
+        branches: &[],
+        library: Some("l10n"),
+        documentation: "turns locale-aware number formatting on or off for its body.",
+    },
+    // `static`
+    Tag {
+        name: "get_media_prefix",
+        closed_by: None,
+        branches: &[],
+        library: Some("static"),
+        documentation: "binds `MEDIA_URL` to a variable.",
+    },
+    Tag {
+        name: "get_static_prefix",
+        closed_by: None,
+        branches: &[],
+        library: Some("static"),
+        documentation: "binds `STATIC_URL` to a variable.",
+    },
+    Tag {
+        name: "static",
+        closed_by: None,
+        branches: &[],
+        library: Some("static"),
+        documentation: "builds the url of a static file.",
+    },
+    // `tz`
+    Tag {
+        name: "get_current_timezone",
+        closed_by: None,
+        branches: &[],
+        library: Some("tz"),
+        documentation: "binds the active time zone's name to a variable.",
+    },
+    Tag {
+        name: "localtime",
+        closed_by: Some("endlocaltime"),
+        branches: &[],
+        library: Some("tz"),
+        documentation: "turns conversion of datetimes to local time on or off for its body.",
+    },
+    Tag {
+        name: "timezone",
+        closed_by: Some("endtimezone"),
+        branches: &[],
+        library: Some("tz"),
+        documentation: "renders its body with the given time zone active.",
+    },
+];
+
+pub(crate) const FILTERS: &[Filter] = &[
+    Filter {
+        name: "add",
+        library: None,
+        documentation: "adds the argument to the value.",
+    },
+    Filter {
+        name: "addslashes",
+        library: None,
+        documentation: "backslash-escapes quotes.",
+    },
+    Filter {
+        name: "capfirst",
+        library: None,
+        documentation: "upper-cases the first character.",
+    },
+    Filter {
+        name: "center",
+        library: None,
+        documentation: "centres the value in a field of the given width.",
+    },
+    Filter {
+        name: "cut",
+        library: None,
+        documentation: "removes every occurrence of the argument.",
+    },
+    Filter {
+        name: "date",
+        library: None,
+        documentation: "formats a date with the given format string.",
+    },
+    Filter {
+        name: "default",
+        library: None,
+        documentation: "uses the argument when the value is falsy.",
+    },
+    Filter {
+        name: "default_if_none",
+        library: None,
+        documentation: "uses the argument only when the value is `None`.",
+    },
+    Filter {
+        name: "dictsort",
+        library: None,
+        documentation: "sorts a list of mappings by the given key.",
+    },
+    Filter {
+        name: "dictsortreversed",
+        library: None,
+        documentation: "sorts a list of mappings by the given key, descending.",
+    },
+    Filter {
+        name: "divisibleby",
+        library: None,
+        documentation: "whether the value divides by the argument.",
+    },
+    Filter {
+        name: "escape",
+        library: None,
+        documentation: "html-escapes the value.",
+    },
+    Filter {
+        name: "escapejs",
+        library: None,
+        documentation: "escapes the value for use in a javascript string.",
+    },
+    Filter {
+        name: "escapeseq",
+        library: None,
+        documentation: "html-escapes each element of a sequence.",
+    },
+    Filter {
+        name: "filesizeformat",
+        library: None,
+        documentation: "formats a byte count as `13 KB`.",
+    },
+    Filter {
+        name: "first",
+        library: None,
+        documentation: "the first element.",
+    },
+    Filter {
+        name: "floatformat",
+        library: None,
+        documentation: "rounds a float to the given number of decimal places.",
+    },
+    Filter {
+        name: "force_escape",
+        library: None,
+        documentation: "html-escapes the value immediately rather than lazily.",
+    },
+    Filter {
+        name: "get_digit",
+        library: None,
+        documentation: "the nth digit of an integer, counted from the right.",
+    },
+    Filter {
+        name: "iriencode",
+        library: None,
+        documentation: "converts an iri to a url-safe string.",
+    },
+    Filter {
+        name: "join",
+        library: None,
+        documentation: "joins a sequence with the argument, like python's `str.join`.",
+    },
+    Filter {
+        name: "json_script",
+        library: None,
+        documentation: "renders the value as json inside a `<script>` with the given id.",
+    },
+    Filter {
+        name: "last",
+        library: None,
+        documentation: "the last element.",
+    },
+    Filter {
+        name: "length",
+        library: None,
+        documentation: "the number of elements.",
+    },
+    Filter {
+        name: "linebreaks",
+        library: None,
+        documentation: "converts newlines into `<p>` and `<br>`.",
+    },
+    Filter {
+        name: "linebreaksbr",
+        library: None,
+        documentation: "converts newlines into `<br>`.",
+    },
+    Filter {
+        name: "linenumbers",
+        library: None,
+        documentation: "prefixes each line with its number.",
+    },
+    Filter {
+        name: "ljust",
+        library: None,
+        documentation: "left-aligns the value in a field of the given width.",
+    },
+    Filter {
+        name: "lower",
+        library: None,
+        documentation: "lower-cases the value.",
+    },
+    Filter {
+        name: "make_list",
+        library: None,
+        documentation: "turns the value into a list of its characters.",
+    },
+    Filter {
+        name: "phone2numeric",
+        library: None,
+        documentation: "converts a phone number's letters into digits.",
+    },
+    Filter {
+        name: "pluralize",
+        library: None,
+        documentation: "the plural suffix, when the value is not one.",
+    },
+    Filter {
+        name: "pprint",
+        library: None,
+        documentation: "pretty-prints the value. for debugging.",
+    },
+    Filter {
+        name: "random",
+        library: None,
+        documentation: "a random element.",
+    },
+    Filter {
+        name: "rjust",
+        library: None,
+        documentation: "right-aligns the value in a field of the given width.",
+    },
+    Filter {
+        name: "safe",
+        library: None,
+        documentation: "marks the value as needing no html escaping.",
+    },
+    Filter {
+        name: "safeseq",
+        library: None,
+        documentation: "marks each element of a sequence as needing no html escaping.",
+    },
+    Filter {
+        name: "slice",
+        library: None,
+        documentation: "slices a sequence, with python's slice syntax.",
+    },
+    Filter {
+        name: "slugify",
+        library: None,
+        documentation: "converts the value into a url slug.",
+    },
+    Filter {
+        name: "stringformat",
+        library: None,
+        documentation: "formats the value with a python `%` format specifier.",
+    },
+    Filter {
+        name: "striptags",
+        library: None,
+        documentation: "removes every html tag.",
+    },
+    Filter {
+        name: "time",
+        library: None,
+        documentation: "formats a time with the given format string.",
+    },
+    Filter {
+        name: "timesince",
+        library: None,
+        documentation: "the time from the value until now, as `3 days`.",
+    },
+    Filter {
+        name: "timeuntil",
+        library: None,
+        documentation: "the time from now until the value, as `3 days`.",
+    },
+    Filter {
+        name: "title",
+        library: None,
+        documentation: "title-cases the value.",
+    },
+    Filter {
+        name: "truncatechars",
+        library: None,
+        documentation: "truncates to the given number of characters.",
+    },
+    Filter {
+        name: "truncatechars_html",
+        library: None,
+        documentation: "truncates to the given number of characters, keeping html tags balanced.",
+    },
+    Filter {
+        name: "truncatewords",
+        library: None,
+        documentation: "truncates to the given number of words.",
+    },
+    Filter {
+        name: "truncatewords_html",
+        library: None,
+        documentation: "truncates to the given number of words, keeping html tags balanced.",
+    },
+    Filter {
+        name: "unordered_list",
+        library: None,
+        documentation: "renders a nested list as `<li>` elements.",
+    },
+    Filter {
+        name: "upper",
+        library: None,
+        documentation: "upper-cases the value.",
+    },
+    Filter {
+        name: "urlencode",
+        library: None,
+        documentation: "url-encodes the value.",
+    },
+    Filter {
+        name: "urlize",
+        library: None,
+        documentation: "turns urls in the text into links.",
+    },
+    Filter {
+        name: "urlizetrunc",
+        library: None,
+        documentation: "turns urls in the text into links, truncating their text.",
+    },
+    Filter {
+        name: "wordcount",
+        library: None,
+        documentation: "the number of words.",
+    },
+    Filter {
+        name: "wordwrap",
+        library: None,
+        documentation: "wraps the text at the given width.",
+    },
+    Filter {
+        name: "yesno",
+        library: None,
+        documentation: "maps `True`, `False` and `None` onto the given words.",
+    },
+    // `i18n`
+    Filter {
+        name: "language_name",
+        library: Some("i18n"),
+        documentation: "the name of the language with the given code.",
+    },
+    Filter {
+        name: "language_name_local",
+        library: Some("i18n"),
+        documentation: "the name of the language with the given code, in that language.",
+    },
+    Filter {
+        name: "language_bidi",
+        library: Some("i18n"),
+        documentation: "whether the language with the given code is right-to-left.",
+    },
+    // `l10n`
+    Filter {
+        name: "localize",
+        library: Some("l10n"),
+        documentation: "formats the number with the active locale's conventions.",
+    },
+    Filter {
+        name: "unlocalize",
+        library: Some("l10n"),
+        documentation: "formats the number without locale conventions.",
+    },
+    // `tz`
+    Filter {
+        name: "localtime",
+        library: Some("tz"),
+        documentation: "converts the datetime to the active time zone.",
+    },
+    Filter {
+        name: "utc",
+        library: Some("tz"),
+        documentation: "converts the datetime to utc.",
+    },
+    Filter {
+        name: "timezone",
+        library: Some("tz"),
+        documentation: "converts the datetime to the given time zone.",
+    },
+];
+
+#[cfg(test)]
+mod tests {
+    use super::{FILTERS, TAGS, end_tag_for, filter, tag};
+
+    #[test]
+    fn tag_names_are_unique() {
+        let mut names: Vec<_> = TAGS.iter().map(|tag| tag.name).collect();
+        names.sort_unstable();
+        let count = names.len();
+        names.dedup();
+        assert_eq!(names.len(), count, "a tag name is listed twice");
+    }
+
+    #[test]
+    fn filter_names_are_unique_within_a_library() {
+        // `localize` and `timezone` are deliberately both a tag and a filter, and
+        // `localtime` is a tag of `tz` as well as a filter of it — but no two
+        // *filters* of the same library may share a name
+        let mut keys: Vec<_> = FILTERS
+            .iter()
+            .map(|filter| (filter.library, filter.name))
+            .collect();
+        keys.sort_unstable();
+        let count = keys.len();
+        keys.dedup();
+        assert_eq!(keys.len(), count, "a filter name is listed twice");
+    }
+
+    #[test]
+    fn every_end_tag_belongs_to_exactly_one_block_tag() {
+        let mut ends: Vec<_> = TAGS.iter().filter_map(|tag| tag.closed_by).collect();
+        ends.sort_unstable();
+        let count = ends.len();
+        ends.dedup();
+        assert_eq!(ends.len(), count, "two block tags share an end tag");
+    }
+
+    #[test]
+    fn end_tags_are_not_themselves_listed_as_tags() {
+        // they are offered from the enclosing block instead, so that
+        // `{% endfor %}` is only ever suggested inside a `{% for %}`
+        for end in TAGS.iter().filter_map(|tag| tag.closed_by) {
+            assert!(tag(end).is_none(), "`{end}` is listed as a tag of its own");
+        }
+    }
+
+    #[test]
+    fn lookup() {
+        assert_eq!(end_tag_for("for"), Some("endfor"));
+        assert_eq!(end_tag_for("include"), None);
+        assert_eq!(end_tag_for("nonexistent"), None);
+        assert_eq!(tag("for").map(|tag| tag.branches), Some(&["empty"][..]));
+        assert_eq!(
+            tag("partialdef").and_then(|tag| tag.closed_by),
+            Some("endpartialdef")
+        );
+        assert_eq!(tag("partial").and_then(|tag| tag.closed_by), None);
+        assert_eq!(filter("upper").map(|filter| filter.library), Some(None));
+        assert_eq!(tag("static").map(|tag| tag.library), Some(Some("static")));
+    }
+}
diff --git a/crates/ty_ide/src/django_template/completion.rs b/crates/ty_ide/src/django_template/completion.rs
new file mode 100644
index 0000000000..623ba4b86b
--- /dev/null
+++ b/crates/ty_ide/src/django_template/completion.rs
@@ -0,0 +1,1084 @@
+//! completions for django templates
+//!
+//! what a template can usefully offer depends entirely on where the cursor is:
+//! the first word of a `{% %}` is a tag, the word after a `|` is a filter, the
+//! word after a `.` is an attribute of whatever precedes it, and the string
+//! argument of an `{% extends %}` is a template path. [`Context`] is that
+//! classification, and everything else here is one context's answer.
+//!
+//! results come back in priority order. the caller is expected to preserve it —
+//! the server does, by deriving each item's `sortText` from its position — because
+//! a lot of the value is in the ordering: the `{% endfor %}` that closes the block
+//! the cursor is in must come before the fifty other tags that are also legal
+//! there.
+
+use compact_str::{CompactString, ToCompactString};
+use ruff_db::files::File;
+use ruff_text_size::{TextRange, TextSize};
+use rustc_hash::FxHashSet;
+use ty_project::Db;
+
+use crate::completion::CompletionKind;
+
+use super::builtins;
+use super::index::{Block, TemplateIndex};
+use super::lexer::{Construct, ConstructKind, Token, TokenKind};
+use super::project::{self, RegistrationKind};
+use super::resolve;
+
+/// how many `{% extends %}` hops the parent chain is followed
+const MAX_INHERITANCE_DEPTH: u32 = 16;
+
+/// an edit a completion carries alongside the text it inserts
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct TemplateEdit {
+    pub range: TextRange,
+    pub text: String,
+}
+
+/// one suggestion for a position in a django template
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct TemplateCompletion {
+    pub label: String,
+    pub kind: CompletionKind,
+    /// the type, route or library the suggestion comes with
+    pub detail: Option<String>,
+    /// markdown documentation
+    pub documentation: Option<String>,
+    /// the text to insert, when it differs from the label
+    pub insert: Option<String>,
+    /// the range this suggestion replaces
+    ///
+    /// the range is always given rather than left to the client's own idea of a
+    /// word, because template names such as `blog/post.html` and namespaced url
+    /// names such as `polls:detail` are not words by any client's definition.
+    pub range: TextRange,
+    /// the `{% load %}` the suggestion needs, when its library isn't loaded yet
+    pub additional_edit: Option<TemplateEdit>,
+}
+
+impl TemplateCompletion {
+    fn new(label: impl Into<String>, kind: CompletionKind, range: TextRange) -> Self {
+        Self {
+            label: label.into(),
+            kind,
+            detail: None,
+            documentation: None,
+            insert: None,
+            range,
+            additional_edit: None,
+        }
+    }
+
+    #[must_use]
+    fn detail(mut self, detail: impl Into<String>) -> Self {
+        self.detail = Some(detail.into());
+        self
+    }
+
+    #[must_use]
+    fn documentation(mut self, documentation: impl Into<String>) -> Self {
+        self.documentation = Some(documentation.into());
+        self
+    }
+}
+
+/// the suggestions for `offset` in the template `file`
+pub(crate) fn completions(
+    db: &dyn Db,
+    file: File,
+    index: &TemplateIndex,
+    source: &str,
+    offset: TextSize,
+) -> Vec<TemplateCompletion> {
+    let Some(construct) = index.lexed().construct_at(offset) else {
+        // outside a construct the file is whatever markup it is, and the editor
+        // completes that far better than this could
+        return Vec::new();
+    };
+
+    let cursor = Cursor::new(index, source, construct, offset);
+
+    match cursor.context() {
+        Context::None => Vec::new(),
+        Context::TagName => tag_names(db, index, source, &cursor),
+        Context::FilterName => filter_names(db, index, &cursor),
+        Context::Member(path) => members(db, file, index, source, offset, &path, &cursor),
+        Context::Variable => variables(db, file, index, offset, &cursor),
+        Context::TemplatePath => template_paths(db, &cursor),
+        Context::StaticPath => static_paths(db, &cursor),
+        Context::UrlName => url_names(db, &cursor),
+        Context::Library => libraries(db, index, &cursor),
+        Context::BlockName => block_names(db, index, &cursor),
+        Context::PartialName => partial_names(db, index, &cursor),
+    }
+}
+
+/// what the cursor's position calls for
+#[derive(Debug, Clone, PartialEq, Eq)]
+enum Context {
+    /// nothing useful; a comment, or a position with no candidates
+    None,
+    /// the first word of a `{% %}`
+    TagName,
+    /// the word after a `|`
+    FilterName,
+    /// the word after a `.`, on the given path
+    Member(Vec<CompactString>),
+    /// a bare name position, where the template's own variables go
+    Variable,
+    /// the template a `{% extends %}`/`{% include %}` names
+    TemplatePath,
+    /// the file a `{% static %}` names
+    StaticPath,
+    /// the route a `{% url %}` reverses
+    UrlName,
+    /// the library a `{% load %}` loads
+    Library,
+    /// the name a `{% block %}` overrides
+    BlockName,
+    /// the fragment a `{% partial %}` renders
+    PartialName,
+}
+
+/// the cursor's position within a construct, resolved once for every rule to use
+struct Cursor<'a> {
+    construct: &'a Construct,
+    source: &'a str,
+    offset: TextSize,
+    /// the construct's tokens with its delimiters dropped
+    tokens: &'a [Token],
+    /// the index in `tokens` of the token the cursor is in or at the end of
+    current: Option<usize>,
+    /// the range the completion replaces
+    range: TextRange,
+}
+
+impl<'a> Cursor<'a> {
+    fn new(
+        index: &'a TemplateIndex,
+        source: &'a str,
+        construct: &'a Construct,
+        offset: TextSize,
+    ) -> Self {
+        let all = index.lexed().construct_tokens(construct);
+        let start = usize::from(
+            all.first()
+                .is_some_and(|token| token.kind == TokenKind::Delimiter),
+        );
+        let end = all
+            .iter()
+            .rposition(|token| token.kind != TokenKind::Delimiter)
+            .map_or(start, |index| index + 1);
+        let tokens = all.get(start..end.max(start)).unwrap_or_default();
+
+        // only a token the user could still be *typing* counts as the one under
+        // the cursor. a cursor at the end of a `.` or a `|` is not editing that
+        // operator, it is starting the word after it — which is the whole reason
+        // `{{ book.` completes attributes rather than variables.
+        let current = tokens
+            .iter()
+            .position(|token| is_word(token.kind) && token.range.contains_inclusive(offset));
+
+        // a partially typed word is replaced whole; a cursor in open space
+        // inserts without replacing anything
+        let range = match current.map(|index| &tokens[index]) {
+            Some(token) if token.kind == TokenKind::String => string_contents(source, token.range),
+            Some(token) => token.range,
+            None => TextRange::empty(offset),
+        };
+
+        Self {
+            construct,
+            source,
+            offset,
+            tokens,
+            current,
+            range,
+        }
+    }
+
+    fn tag(&self) -> &'a str {
+        self.construct.name.map_or("", |range| &self.source[range])
+    }
+
+    /// the token before the cursor, skipping the one being typed
+    fn previous(&self) -> Option<&'a Token> {
+        let before = match self.current {
+            Some(index) => index,
+            None => self
+                .tokens
+                .iter()
+                .position(|token| token.range.start() >= self.offset)
+                .unwrap_or(self.tokens.len()),
+        };
+
+        self.tokens.get(before.checked_sub(1)?)
+    }
+
+    /// how many argument tokens the cursor is preceded by
+    ///
+    /// the tag name is not one of them, so the first argument of `{% url %}` is
+    /// at position zero.
+    fn argument_position(&self) -> usize {
+        let tag_name = usize::from(self.construct.name.is_some());
+        let before = match self.current {
+            Some(index) => index,
+            None => self
+                .tokens
+                .iter()
+                .position(|token| token.range.start() >= self.offset)
+                .unwrap_or(self.tokens.len()),
+        };
+
+        before.saturating_sub(tag_name)
+    }
+
+    /// whether the cursor is still on the tag's own name
+    fn on_tag_name(&self) -> bool {
+        match self.construct.name {
+            // no name typed yet: everything up to the closing delimiter is the
+            // name's position
+            None => true,
+            Some(name) => self.offset <= name.end(),
+        }
+    }
+
+    fn context(&self) -> Context {
+        if self.construct.kind == ConstructKind::Comment {
+            return Context::None;
+        }
+
+        if self.construct.kind == ConstructKind::Tag {
+            if self.on_tag_name() {
+                return Context::TagName;
+            }
+
+            // a tag whose argument names something other than a variable
+            let position = self.argument_position();
+            match (self.tag(), position) {
+                ("extends" | "include", 0) => return Context::TemplatePath,
+                ("static", 0) => return Context::StaticPath,
+                ("url", 0) => return Context::UrlName,
+                ("load", _) => return Context::Library,
+                ("block", 0) => return Context::BlockName,
+                ("partial", 0) => return Context::PartialName,
+                _ => {}
+            }
+        }
+
+        match self.previous() {
+            Some(token) if self.source[token.range] == *"|" => Context::FilterName,
+            Some(token) if self.source[token.range] == *"." => match self.path_before() {
+                path if path.is_empty() => Context::None,
+                path => Context::Member(path),
+            },
+            _ => Context::Variable,
+        }
+    }
+
+    /// the dotted path written immediately before the cursor's `.`
+    fn path_before(&self) -> Vec<CompactString> {
+        let Some(dot) = self.current.unwrap_or(self.tokens.len()).checked_sub(1) else {
+            return Vec::new();
+        };
+
+        let mut segments = Vec::new();
+        let mut index = dot;
+
+        // walk back over `… . name . name`, ending on the path's leading name
+        while let Some(previous) = index.checked_sub(1) {
+            let Some(token) = self.tokens.get(previous) else {
+                break;
+            };
+            match token.kind {
+                TokenKind::Attribute => {
+                    segments.push(self.source[token.range].to_compact_string());
+                }
+                TokenKind::Variable => {
+                    segments.push(self.source[token.range].to_compact_string());
+                    break;
+                }
+                _ => break,
+            }
+
+            // step over the `.` joining this segment to the previous one
+            let Some(dot) = previous.checked_sub(1) else {
+                break;
+            };
+            if self
+                .tokens
+                .get(dot)
+                .is_none_or(|token| self.source[token.range] != *".")
+            {
+                break;
+            }
+            index = dot;
+        }
+
+        segments.reverse();
+        segments
+    }
+}
+
+/// whether a token of this kind is a word the user can be part-way through
+fn is_word(kind: TokenKind) -> bool {
+    matches!(
+        kind,
+        TokenKind::TagName
+            | TokenKind::FilterName
+            | TokenKind::Variable
+            | TokenKind::Attribute
+            | TokenKind::KeywordArgument
+            | TokenKind::Keyword
+            | TokenKind::BuiltinConstant
+            | TokenKind::String
+            | TokenKind::Number
+    )
+}
+
+/// the contents of a string literal, its quotes excluded
+fn string_contents(source: &str, range: TextRange) -> TextRange {
+    let text = &source[range];
+    let Some(quote) = text.chars().next() else {
+        return range;
+    };
+    if !matches!(quote, '"' | '\'') {
+        return range;
+    }
+
+    let start = range.start() + TextSize::from(1);
+    let end = if text.len() > 1 && text.ends_with(quote) {
+        range.end() - TextSize::from(1)
+    } else {
+        range.end()
+    };
+
+    TextRange::new(start, end.max(start))
+}
+
+fn tag_names(
+    db: &dyn Db,
+    index: &TemplateIndex,
+    source: &str,
+    cursor: &Cursor<'_>,
+) -> Vec<TemplateCompletion> {
+    let mut completions = Vec::new();
+    let open = index.open_blocks_at(cursor.construct.range.start());
+
+    // the tag that closes the block the cursor is in is nearly always the one
+    // wanted, so it leads
+    for block in &open {
+        if block.closed {
+            continue;
+        }
+        completions.push(
+            TemplateCompletion::new(
+                block.end_tag.as_str(),
+                CompletionKind::Keyword,
+                cursor.range,
+            )
+            .detail(format!("closes {}", opening_tag(source, block)))
+            .documentation(format!("closes the `{{% {} %}}` above.", block.name)),
+        );
+    }
+
+    if let Some(innermost) = open.first() {
+        for branch in builtins::tag(&innermost.name)
+            .map(|tag| tag.branches)
+            .unwrap_or_default()
+        {
+            completions.push(
+                TemplateCompletion::new(*branch, CompletionKind::Keyword, cursor.range)
+                    .detail(format!("branch of {}", opening_tag(source, innermost))),
+            );
+        }
+    }
+
+    let loaded = loaded_libraries(index);
+    let load_edit = |library: Option<&str>| load_edit_for(index, &loaded, library);
+
+    for tag in builtins::TAGS {
+        let mut completion =
+            TemplateCompletion::new(tag.name, CompletionKind::Keyword, cursor.range)
+                .documentation(tag.documentation);
+        if let Some(library) = tag.library {
+            completion = completion.detail(format!("{{% load {library} %}}"));
+        }
+        completion.additional_edit = load_edit(tag.library);
+        completions.push(completion);
+    }
+
+    for registration in project::registrations(db, db.project()) {
+        if registration.kind == RegistrationKind::Filter {
+            continue;
+        }
+
+        let mut completion = TemplateCompletion::new(
+            registration.name.as_str(),
+            CompletionKind::Keyword,
+            cursor.range,
+        )
+        .detail(format!("{{% load {} %}}", registration.library));
+        completion.documentation = registration
+            .documentation
+            .as_deref()
+            .map(ToString::to_string);
+        completion.additional_edit = load_edit(Some(&registration.library));
+        completions.push(completion);
+    }
+
+    completions
+}
+
+/// how an open block's tag reads, for a closing tag's detail line
+fn opening_tag(source: &str, block: &Block) -> String {
+    source[block.open_range].trim().to_string()
+}
+
+fn filter_names(
+    db: &dyn Db,
+    index: &TemplateIndex,
+    cursor: &Cursor<'_>,
+) -> Vec<TemplateCompletion> {
+    let loaded = loaded_libraries(index);
+    let mut completions = Vec::new();
+
+    for filter in builtins::FILTERS {
+        let mut completion =
+            TemplateCompletion::new(filter.name, CompletionKind::Function, cursor.range)
+                .documentation(filter.documentation);
+        if let Some(library) = filter.library {
+            completion = completion.detail(format!("{{% load {library} %}}"));
+        }
+        completion.additional_edit = load_edit_for(index, &loaded, filter.library);
+        completions.push(completion);
+    }
+
+    for registration in project::registrations(db, db.project()) {
+        if registration.kind != RegistrationKind::Filter {
+            continue;
+        }
+
+        let mut completion = TemplateCompletion::new(
+            registration.name.as_str(),
+            CompletionKind::Function,
+            cursor.range,
+        )
+        .detail(format!("{{% load {} %}}", registration.library));
+        completion.documentation = registration
+            .documentation
+            .as_deref()
+            .map(ToString::to_string);
+        completion.additional_edit = load_edit_for(index, &loaded, Some(&registration.library));
+        completions.push(completion);
+    }
+
+    completions
+}
+
+fn members(
+    db: &dyn Db,
+    file: File,
+    index: &TemplateIndex,
+    source: &str,
+    offset: TextSize,
+    path: &[CompactString],
+    cursor: &Cursor<'_>,
+) -> Vec<TemplateCompletion> {
+    let segments: Vec<&str> = path.iter().map(CompactString::as_str).collect();
+    let Some(ty) = resolve::path_type(db, file, index, source, offset, &segments) else {
+        return Vec::new();
+    };
+
+    resolve::members(db, ty)
+        .into_iter()
+        .map(|member| {
+            TemplateCompletion::new(member.name.as_str(), CompletionKind::Field, cursor.range)
+                .detail(member.ty.display(db).to_string())
+        })
+        .collect()
+}
+
+fn variables(
+    db: &dyn Db,
+    file: File,
+    index: &TemplateIndex,
+    offset: TextSize,
+    cursor: &Cursor<'_>,
+) -> Vec<TemplateCompletion> {
+    let mut completions = Vec::new();
+    let mut seen = FxHashSet::default();
+
+    // a name the template itself binds shadows one from the context, so it goes
+    // first for the same reason it wins at render time
+    for binding in index.bindings_at(offset) {
+        if seen.insert(binding.name.clone()) {
+            completions.push(
+                TemplateCompletion::new(
+                    binding.name.as_str(),
+                    CompletionKind::Variable,
+                    cursor.range,
+                )
+                .detail("bound by this template"),
+            );
+        }
+    }
+
+    for variable in resolve::context_variables(db, file) {
+        if !seen.insert(variable.name.clone()) {
+            continue;
+        }
+
+        let mut completion = TemplateCompletion::new(
+            variable.name.as_str(),
+            CompletionKind::Variable,
+            cursor.range,
+        );
+        completion.detail = variable
+            .value
+            .and_then(|value| resolve::expression_type(db, variable.file, value))
+            .map(|ty| ty.display(db).to_string())
+            .or_else(|| Some("from the view's context".to_string()));
+        completions.push(completion);
+    }
+
+    completions
+}
+
+fn template_paths(db: &dyn Db, cursor: &Cursor<'_>) -> Vec<TemplateCompletion> {
+    discovered(project::template_files(db, db.project()), cursor)
+}
+
+fn static_paths(db: &dyn Db, cursor: &Cursor<'_>) -> Vec<TemplateCompletion> {
+    discovered(project::static_files(db, db.project()), cursor)
+}
+
+/// one suggestion per name found under the project's template or static roots
+///
+/// two apps may both hold a `base.html`; django's loader resolves the name to
+/// whichever app comes first, so the name is offered once, with the path that
+/// would win shown alongside it.
+fn discovered(files: &[project::DiscoveredFile], cursor: &Cursor<'_>) -> Vec<TemplateCompletion> {
+    let mut seen = FxHashSet::default();
+
+    files
+        .iter()
+        .filter(|file| seen.insert(file.name.clone()))
+        .map(|file| {
+            TemplateCompletion::new(file.name.as_str(), CompletionKind::File, cursor.range)
+                .detail(file.path.as_str())
+        })
+        .collect()
+}
+
+fn url_names(db: &dyn Db, cursor: &Cursor<'_>) -> Vec<TemplateCompletion> {
+    project::url_names(db, db.project())
+        .iter()
+        .map(|url| {
+            let mut completion =
+                TemplateCompletion::new(url.name.as_str(), CompletionKind::Reference, cursor.range);
+            completion.detail = url.route.as_deref().map(ToString::to_string);
+            completion
+        })
+        .collect()
+}
+
+fn libraries(db: &dyn Db, index: &TemplateIndex, cursor: &Cursor<'_>) -> Vec<TemplateCompletion> {
+    let loaded = loaded_libraries(index);
+    let mut completions = Vec::new();
+    let mut seen = FxHashSet::default();
+
+    for library in builtins::LIBRARIES {
+        if loaded.contains(&library.to_compact_string()) {
+            continue;
+        }
+        seen.insert(library.to_compact_string());
+        completions.push(
+            TemplateCompletion::new(*library, CompletionKind::Module, cursor.range)
+                .detail("django"),
+        );
+    }
+
+    for registration in project::registrations(db, db.project()) {
+        if loaded.contains(&registration.library) || !seen.insert(registration.library.clone()) {
+            continue;
+        }
+        completions.push(
+            TemplateCompletion::new(
+                registration.library.as_str(),
+                CompletionKind::Module,
+                cursor.range,
+            )
+            .detail("this project"),
+        );
+    }
+
+    completions
+}
+
+fn block_names(db: &dyn Db, index: &TemplateIndex, cursor: &Cursor<'_>) -> Vec<TemplateCompletion> {
+    // a `{% block %}` in a child template is only useful when it overrides one of
+    // the parent's, so those are exactly what is offered
+    let defined: FxHashSet<_> = index
+        .blocks()
+        .iter()
+        .map(|block| block.name.clone())
+        .collect();
+
+    inherited(db, index, |parent| {
+        parent
+            .blocks()
+            .iter()
+            .map(|block| block.name.clone())
+            .collect()
+    })
+    .into_iter()
+    .filter(|name| !defined.contains(name))
+    .map(|name| {
+        TemplateCompletion::new(name.as_str(), CompletionKind::Function, cursor.range)
+            .detail("overrides the parent template's block")
+    })
+    .collect()
+}
+
+fn partial_names(
+    db: &dyn Db,
+    index: &TemplateIndex,
+    cursor: &Cursor<'_>,
+) -> Vec<TemplateCompletion> {
+    let mut names: Vec<CompactString> = index
+        .partials()
+        .iter()
+        .map(|partial| partial.name.clone())
+        .collect();
+
+    // a partial defined by a template this one extends is in scope here too
+    names.extend(inherited(db, index, |parent| {
+        parent
+            .partials()
+            .iter()
+            .map(|partial| partial.name.clone())
+            .collect()
+    }));
+
+    let mut seen = FxHashSet::default();
+    names
+        .into_iter()
+        .filter(|name| seen.insert(name.clone()))
+        .map(|name| {
+            TemplateCompletion::new(name.as_str(), CompletionKind::Function, cursor.range)
+                .detail("a fragment defined with `{% partialdef %}`")
+        })
+        .collect()
+}
+
+/// collect `names` from every template up the `{% extends %}` chain
+fn inherited(
+    db: &dyn Db,
+    index: &TemplateIndex,
+    names: impl Fn(&TemplateIndex) -> Vec<CompactString>,
+) -> Vec<CompactString> {
+    let mut collected = Vec::new();
+    let mut seen = FxHashSet::default();
+    let mut parent = index.extends().map(|reference| reference.name.clone());
+
+    for _ in 0..MAX_INHERITANCE_DEPTH {
+        let Some(name) = parent.take() else { break };
+        let Some(file) = project::resolve_template(db, &name) else {
+            break;
+        };
+        if !seen.insert(file) {
+            // a cycle in the inheritance chain; django would fail to render it,
+            // but the editor must not hang on it
+            break;
+        }
+
+        let parent_index = super::template_index(db, file);
+        collected.extend(names(parent_index));
+        parent = parent_index
+            .extends()
+            .map(|reference| reference.name.clone());
+    }
+
+    collected
+}
+
+/// the libraries the template has already `{% load %}`ed
+fn loaded_libraries(index: &TemplateIndex) -> FxHashSet<CompactString> {
+    index
+        .loads()
+        .iter()
+        .map(|load| load.library.clone())
+        .collect()
+}
+
+/// the `{% load %}` a suggestion from `library` needs, when it isn't loaded yet
+fn load_edit_for(
+    index: &TemplateIndex,
+    loaded: &FxHashSet<CompactString>,
+    library: Option<&str>,
+) -> Option<TemplateEdit> {
+    let library = library?;
+    if loaded.contains(&library.to_compact_string()) {
+        return None;
+    }
+
+    // `{% extends %}` has to stay the first tag in the file, so a `{% load %}`
+    // goes after it rather than above it
+    let after_extends = index.extends().and_then(|reference| {
+        index
+            .lexed()
+            .constructs()
+            .iter()
+            .find(|construct| construct.range.contains_range(reference.range))
+            .map(|construct| construct.range.end())
+    });
+    let start = after_extends.unwrap_or_default();
+
+    Some(TemplateEdit {
+        range: TextRange::empty(start),
+        text: if start == TextSize::new(0) {
+            format!("{{% load {library} %}}\n")
+        } else {
+            format!("\n{{% load {library} %}}")
+        },
+    })
+}
+
+#[cfg(test)]
+mod tests {
+    use crate::django_template::django_template_completions;
+    use crate::django_template::tests::TemplateTest;
+
+    /// a small but complete django project: a couple of models, a view that
+    /// renders a template with them, a url configuration, and a tag library
+    fn project(template: &str) -> TemplateTest {
+        TemplateTest::new(&[
+            (
+                "blog/models.py",
+                "
+                class Author:
+                    name: str
+                    email: str
+
+                class Book:
+                    title: str
+                    author: Author
+                ",
+            ),
+            (
+                "blog/views.py",
+                "
+                from blog.models import Book
+
+                def post(request):
+                    book = Book()
+                    return render(request, 'blog/post.html', {'book': book, 'shelf': [book]})
+                ",
+            ),
+            (
+                "blog/urls.py",
+                "
+                app_name = 'blog'
+
+                urlpatterns = [
+                    path('books/<int:pk>/', detail, name='detail'),
+                    path('books/', index, name='index'),
+                ]
+                ",
+            ),
+            (
+                "blog/templatetags/blog_extras.py",
+                "
+                from django import template
+
+                register = template.Library()
+
+                @register.filter
+                def shout(value):
+                    '''upper-cases and adds an exclamation mark.'''
+                    return value
+
+                @register.simple_tag(name='book_count')
+                def count_books():
+                    return 0
+                ",
+            ),
+            (
+                "blog/templates/blog/base.html",
+                "{% block content %}{% endblock %}",
+            ),
+            ("blog/static/blog/app.css", "body {}"),
+            ("blog/templates/blog/post.html", template),
+        ])
+    }
+
+    #[test]
+    fn a_position_outside_a_construct_offers_nothing() {
+        assert!(project("<p>he<CURSOR>llo</p>").completions().is_empty());
+    }
+
+    #[test]
+    fn a_comment_offers_nothing() {
+        assert!(project("{# to<CURSOR>do #}").completions().is_empty());
+    }
+
+    #[test]
+    fn the_first_word_of_a_tag_offers_tag_names() {
+        let completions = project("{% <CURSOR> %}").completions();
+
+        assert!(completions.contains(&"extends".to_string()));
+        assert!(completions.contains(&"include".to_string()));
+        assert!(completions.contains(&"partialdef".to_string()));
+        assert!(
+            completions.contains(&"book_count".to_string()),
+            "the project's own tag is offered too"
+        );
+        assert!(
+            !completions.contains(&"shout".to_string()),
+            "a filter is not a tag"
+        );
+    }
+
+    #[test]
+    fn the_tag_closing_the_enclosing_block_is_offered_first() {
+        let completions = project("{% for book in shelf %}{% <CURSOR>").completions();
+
+        assert_eq!(completions[0], "endfor");
+        assert_eq!(
+            completions[1], "empty",
+            "the branch tag of the enclosing block comes next"
+        );
+    }
+
+    #[test]
+    fn nested_blocks_offer_their_closing_tags_innermost_first() {
+        let completions = project("{% for b in shelf %}{% if b %}{% <CURSOR>").completions();
+        assert_eq!(&completions[..2], ["endif", "endfor"]);
+    }
+
+    #[test]
+    fn a_block_that_is_already_closed_does_not_offer_its_closing_tag() {
+        // the structure is complete, so what the user is adding here is a branch
+        // of the `{% if %}`, never a second `{% endif %}`
+        let completions =
+            project("{% for b in shelf %}{% if b %}{% <CURSOR> %}{% endif %}{% endfor %}")
+                .completions();
+
+        assert_eq!(&completions[..2], ["elif", "else"]);
+    }
+
+    #[test]
+    fn a_closed_block_does_not_offer_its_closing_tag_again() {
+        let completions = project("{% if x %}{% endif %}{% <CURSOR> %}").completions();
+        assert_ne!(completions[0], "endif");
+    }
+
+    #[test]
+    fn a_partially_typed_tag_name_is_replaced_whole() {
+        let source = "{% ext<CURSOR> %}";
+        let test = project(source);
+        let completions = django_template_completions(&test.db, test.file, test.offset);
+
+        let extends = completions
+            .iter()
+            .find(|completion| completion.label == "extends")
+            .expect("`extends` to be offered");
+
+        assert_eq!(
+            &"{% ext %}"[usize::from(extends.range.start())..usize::from(extends.range.end())],
+            "ext"
+        );
+    }
+
+    #[test]
+    fn the_word_after_a_pipe_offers_filters() {
+        let completions = project("{{ book.title|<CURSOR> }}").completions();
+
+        assert!(completions.contains(&"upper".to_string()));
+        assert!(completions.contains(&"truncatewords".to_string()));
+        assert!(
+            completions.contains(&"shout".to_string()),
+            "the project's own filter is offered too"
+        );
+        assert!(
+            !completions.contains(&"book_count".to_string()),
+            "a tag is not a filter"
+        );
+    }
+
+    #[test]
+    fn a_tag_from_an_unloaded_library_carries_the_load_it_needs() {
+        let test = project("{% <CURSOR> %}");
+        let completions = django_template_completions(&test.db, test.file, test.offset);
+
+        let edit = completions
+            .iter()
+            .find(|completion| completion.label == "static")
+            .and_then(|completion| completion.additional_edit.clone())
+            .expect("`{% static %}` to come with the load it needs");
+
+        assert_eq!(edit.text, "{% load static %}\n");
+        assert!(
+            edit.range.is_empty(),
+            "the load is inserted, not a replacement"
+        );
+        assert_eq!(u32::from(edit.range.start()), 0, "at the top of the file");
+    }
+
+    #[test]
+    fn a_load_is_written_below_an_extends_rather_than_above_it() {
+        let source = "{% extends 'blog/base.html' %}\n{% <CURSOR> %}";
+        let test = project(source);
+        let completions = django_template_completions(&test.db, test.file, test.offset);
+
+        let edit = completions
+            .iter()
+            .find(|completion| completion.label == "static")
+            .and_then(|completion| completion.additional_edit.clone())
+            .expect("`{% static %}` to come with the load it needs");
+
+        assert_eq!(edit.text, "\n{% load static %}");
+        assert_eq!(
+            &source[..usize::from(edit.range.start())],
+            "{% extends 'blog/base.html' %}"
+        );
+    }
+
+    #[test]
+    fn an_already_loaded_library_needs_no_load() {
+        let test = project("{% load static %}{% <CURSOR> %}");
+        let completions = django_template_completions(&test.db, test.file, test.offset);
+
+        let static_tag = completions
+            .iter()
+            .find(|completion| completion.label == "static")
+            .expect("`static` to be offered");
+        assert!(static_tag.additional_edit.is_none());
+    }
+
+    #[test]
+    fn extends_offers_the_projects_templates() {
+        let completions = project("{% extends '<CURSOR>' %}").completions();
+        assert_eq!(completions, ["blog/base.html", "blog/post.html"]);
+    }
+
+    #[test]
+    fn include_offers_the_projects_templates() {
+        let completions = project("{% include \"<CURSOR>\" %}").completions();
+        assert!(completions.contains(&"blog/base.html".to_string()));
+    }
+
+    #[test]
+    fn a_template_path_completion_replaces_the_string_but_not_its_quotes() {
+        let source = "{% extends 'blog/<CURSOR>' %}";
+        let test = project(source);
+        let completions = django_template_completions(&test.db, test.file, test.offset);
+
+        let range = completions[0].range;
+        assert_eq!(&source[usize::from(range.start())..], "blog/<CURSOR>' %}");
+    }
+
+    #[test]
+    fn url_offers_the_projects_route_names_namespaced() {
+        let completions = project("{% url '<CURSOR>' %}").detailed();
+        assert_eq!(
+            completions,
+            ["blog:detail — books/<int:pk>/", "blog:index — books/"]
+        );
+    }
+
+    #[test]
+    fn static_offers_the_projects_assets() {
+        let completions = project("{% load static %}{% static '<CURSOR>' %}").completions();
+        assert_eq!(completions, ["blog/app.css"]);
+    }
+
+    #[test]
+    fn load_offers_the_libraries_not_yet_loaded() {
+        let completions = project("{% load <CURSOR> %}").detailed();
+
+        assert!(completions.contains(&"static — django".to_string()));
+        assert!(completions.contains(&"blog_extras — this project".to_string()));
+    }
+
+    #[test]
+    fn load_does_not_offer_a_library_already_loaded() {
+        let completions = project("{% load i18n %}{% load <CURSOR> %}").completions();
+        assert!(!completions.contains(&"i18n".to_string()));
+    }
+
+    #[test]
+    fn a_bare_name_offers_the_views_context() {
+        let completions = project("{{ <CURSOR> }}").completions();
+        assert_eq!(completions, ["book", "shelf"]);
+    }
+
+    #[test]
+    fn a_bare_name_offers_the_templates_own_bindings_first() {
+        let completions =
+            project("{% for book in shelf %}{{ <CURSOR> }}{% endfor %}").completions();
+        assert_eq!(completions, ["book", "forloop", "shelf"]);
+    }
+
+    #[test]
+    fn a_context_variable_shows_the_type_the_view_gives_it() {
+        let completions = project("{{ <CURSOR> }}").detailed();
+        assert_eq!(completions[0], "book — Book");
+    }
+
+    #[test]
+    fn the_word_after_a_dot_offers_the_types_attributes() {
+        let completions = project("{{ book.<CURSOR> }}").detailed();
+        assert_eq!(completions, ["author — Author", "title — str"]);
+    }
+
+    #[test]
+    fn attributes_are_followed_through_a_whole_path() {
+        let completions = project("{{ book.author.<CURSOR> }}").detailed();
+        assert_eq!(completions, ["email — str", "name — str"]);
+    }
+
+    #[test]
+    fn a_loop_variable_takes_the_element_type_of_what_it_loops_over() {
+        let completions =
+            project("{% for entry in shelf %}{{ entry.<CURSOR> }}{% endfor %}").detailed();
+        assert_eq!(completions, ["author — Author", "title — str"]);
+    }
+
+    #[test]
+    fn a_with_alias_carries_the_type_of_the_path_it_binds() {
+        let completions =
+            project("{% with writer=book.author %}{{ writer.<CURSOR> }}{% endwith %}").detailed();
+        assert_eq!(completions, ["email — str", "name — str"]);
+    }
+
+    #[test]
+    fn an_unresolvable_path_offers_nothing_rather_than_guessing() {
+        assert!(project("{{ mystery.<CURSOR> }}").completions().is_empty());
+    }
+
+    #[test]
+    fn partial_offers_the_fragments_this_template_defines() {
+        let completions =
+            project("{% partialdef card %}{% endpartialdef %}{% partial <CURSOR> %}").completions();
+        assert_eq!(completions, ["card"]);
+    }
+
+    #[test]
+    fn block_offers_the_blocks_of_the_template_being_extended() {
+        let completions =
+            project("{% extends 'blog/base.html' %}{% block <CURSOR> %}").completions();
+        assert_eq!(completions, ["content"]);
+    }
+
+    #[test]
+    fn block_does_not_offer_a_block_this_template_already_overrides() {
+        let completions = project(
+            "{% extends 'blog/base.html' %}{% block content %}{% endblock %}{% block <CURSOR> %}",
+        )
+        .completions();
+        assert!(completions.is_empty());
+    }
+}
diff --git a/crates/ty_ide/src/django_template/goto.rs b/crates/ty_ide/src/django_template/goto.rs
new file mode 100644
index 0000000000..4c57cd1eec
--- /dev/null
+++ b/crates/ty_ide/src/django_template/goto.rs
@@ -0,0 +1,492 @@
+//! go-to-definition for django templates
+//!
+//! nearly every name a template writes points somewhere: a `{% extends %}` at
+//! another template, a `{% partial %}` at the `{% partialdef %}` that declares it,
+//! a `{% url %}` at the `path(…, name=…)` that names the route, a tag or filter at
+//! the python function registered under it, and a `{{ variable }}` at the view
+//! that put it in the context.
+
+use ruff_db::files::{File, FileRange};
+use ruff_text_size::{TextRange, TextSize};
+use ty_project::Db;
+
+use crate::{HasNavigationTargets, NavigationTarget, NavigationTargets, RangedValue};
+
+use super::index::TemplateIndex;
+use super::lexer::{ConstructKind, Token, TokenKind};
+use super::project::{self, RegistrationKind};
+use super::resolve::{self, Origin};
+
+/// how many `{% extends %}` hops a partial or block is looked for through
+const MAX_INHERITANCE_DEPTH: u32 = 16;
+
+/// where the name at `offset` of the template `file` is defined
+pub(crate) fn goto_definition(
+    db: &dyn Db,
+    file: File,
+    index: &TemplateIndex,
+    source: &str,
+    offset: TextSize,
+) -> Option<RangedValue<NavigationTargets>> {
+    let construct = index.lexed().construct_at(offset)?;
+    if construct.kind == ConstructKind::Comment {
+        return None;
+    }
+
+    let tokens = index.lexed().construct_tokens(construct);
+    let token = *tokens
+        .iter()
+        .find(|token| token.range.contains_inclusive(offset))?;
+
+    let site = Site {
+        db,
+        file,
+        index,
+        source,
+        offset,
+        tag: construct.name.map_or("", |range| &source[range]),
+        tokens,
+        token,
+    };
+
+    let targets = site.definition()?;
+
+    (!targets.is_empty()).then(|| RangedValue {
+        range: FileRange::new(file, token.range),
+        value: targets,
+    })
+}
+
+/// the one token a navigation starts from, with everything needed to interpret it
+struct Site<'a> {
+    db: &'a dyn Db,
+    file: File,
+    index: &'a TemplateIndex,
+    source: &'a str,
+    offset: TextSize,
+    /// the name of the tag the token sits in, or `""` outside a tag
+    tag: &'a str,
+    /// the tokens of the construct the token sits in
+    tokens: &'a [Token],
+    token: Token,
+}
+
+impl Site<'_> {
+    fn text(&self) -> &str {
+        &self.source[self.token.range]
+    }
+
+    fn definition(&self) -> Option<NavigationTargets> {
+        match self.token.kind {
+            TokenKind::TagName => Some(self.registration(false)),
+            TokenKind::FilterName => Some(self.registration(true)),
+            TokenKind::String => self.string_definition(),
+            TokenKind::Variable => self.name_definition(),
+            TokenKind::Attribute => {
+                // the attribute itself has no template-visible declaration, so
+                // this navigates to the type the attribute is read off: for a
+                // django model field that is the model class
+                let segments = path_up_to(self.source, self.tokens, self.token, false);
+                let ty = resolve::path_type(
+                    self.db,
+                    self.file,
+                    self.index,
+                    self.source,
+                    self.offset,
+                    &segments,
+                )?;
+                Some(ty.navigation_targets(self.db))
+            }
+            _ => None,
+        }
+    }
+
+    /// the python function the token's name is registered by
+    fn registration(&self, filter: bool) -> NavigationTargets {
+        let name = self.text();
+
+        project::registrations(self.db, self.db.project())
+            .iter()
+            .filter(|registration| {
+                (registration.kind == RegistrationKind::Filter) == filter
+                    && registration.name == name
+            })
+            .map(|registration| NavigationTarget::new(registration.file, registration.range))
+            .collect()
+    }
+
+    /// what a string argument names, which depends on the tag it sits in
+    fn string_definition(&self) -> Option<NavigationTargets> {
+        let db = self.db;
+        let value = string_contents(self.source, self.token.range);
+
+        match self.tag {
+            "extends" | "include" => {
+                let reference = self
+                    .index
+                    .extends()
+                    .into_iter()
+                    .chain(self.index.includes())
+                    .find(|reference| reference.range == value)?;
+
+                let target = project::resolve_template(db, &reference.name)?;
+                let range = match &reference.partial {
+                    // `blog.html#comment-item` addresses one fragment of it
+                    Some(partial) => super::template_index(db, target)
+                        .partials()
+                        .iter()
+                        .find(|candidate| candidate.name == *partial)
+                        .map(|candidate| candidate.name_range)?,
+                    None => TextRange::default(),
+                };
+
+                Some(NavigationTargets::from_iter([NavigationTarget::new(
+                    target, range,
+                )]))
+            }
+            "url" => {
+                let name = &self.source[value];
+                Some(
+                    project::url_names(db, db.project())
+                        .iter()
+                        .filter(|url| url.name == name)
+                        .map(|url| NavigationTarget::new(url.file, url.range))
+                        .collect(),
+                )
+            }
+            _ => None,
+        }
+    }
+
+    /// what a bare name refers to, which again depends on the tag it sits in
+    fn name_definition(&self) -> Option<NavigationTargets> {
+        let (db, file, index) = (self.db, self.file, self.index);
+        let text = self.text();
+
+        match self.tag {
+            // `{% load static %}` points at the module the library lives in
+            "load" => Some(
+                project::registrations(db, db.project())
+                    .iter()
+                    .filter(|registration| registration.library == text)
+                    .map(|registration| {
+                        NavigationTarget::new(registration.file, TextRange::default())
+                    })
+                    .collect(),
+            ),
+            // `{% partial card %}` points at the `{% partialdef card %}`, which
+            // this template may well declare itself
+            "partial" => definition_in_chain(db, file, index, text, false, TemplateIndex::partials),
+            // a `{% block %}` *is* a definition, so navigating from one is only
+            // useful if it goes to the block in the parent that it overrides
+            "block" => definition_in_chain(db, file, index, text, true, TemplateIndex::blocks),
+            _ => {
+                // a name in a path resolves through the path's leading segment
+                let segments = path_up_to(self.source, self.tokens, self.token, true);
+                let root = segments.first()?;
+                if *root != text {
+                    // the name is not the path's root, so it is an attribute the
+                    // `Attribute` arm would have handled had it lexed as one
+                    return None;
+                }
+
+                match resolve::resolve_root(db, file, index, self.offset, root)? {
+                    Origin::Binding(binding) => {
+                        Some(NavigationTargets::from_iter([NavigationTarget::new(
+                            file,
+                            binding.range,
+                        )]))
+                    }
+                    Origin::Context(variable) => {
+                        Some(NavigationTargets::from_iter([NavigationTarget::new(
+                            variable.file,
+                            variable.range,
+                        )]))
+                    }
+                }
+            }
+        }
+    }
+}
+
+/// the definition named `name`, looked for in this template and then up its
+/// `{% extends %}` chain
+///
+/// `skip_current` starts the search at the parent, for a name whose occurrence in
+/// this template is itself the definition.
+fn definition_in_chain(
+    db: &dyn Db,
+    file: File,
+    index: &TemplateIndex,
+    name: &str,
+    skip_current: bool,
+    definitions: impl Fn(&TemplateIndex) -> &[super::index::Definition],
+) -> Option<NavigationTargets> {
+    let mut current = (file, index);
+    let mut searchable = !skip_current;
+    let mut seen = vec![file];
+
+    for _ in 0..MAX_INHERITANCE_DEPTH {
+        let (file, index) = current;
+
+        if searchable
+            && let Some(definition) = definitions(index)
+                .iter()
+                .find(|definition| definition.name == name)
+        {
+            return Some(NavigationTargets::from_iter([NavigationTarget::new(
+                file,
+                definition.name_range,
+            )]));
+        }
+
+        let parent = index.extends()?;
+        let parent_file = project::resolve_template(db, &parent.name)?;
+        if seen.contains(&parent_file) {
+            // an inheritance cycle would loop forever
+            return None;
+        }
+
+        seen.push(parent_file);
+        current = (parent_file, super::template_index(db, parent_file));
+        searchable = true;
+    }
+
+    None
+}
+
+/// the path segments up to and including `token`
+///
+/// `inclusive` keeps `token` itself, for a name whose own type is wanted; leaving
+/// it out gives the type the name is an attribute *of*.
+fn path_up_to<'src>(
+    source: &'src str,
+    tokens: &[Token],
+    token: Token,
+    inclusive: bool,
+) -> Vec<&'src str> {
+    let Some(position) = tokens
+        .iter()
+        .position(|candidate| candidate.range == token.range)
+    else {
+        return Vec::new();
+    };
+
+    // walk back to the path's leading name
+    let mut start = position;
+    while start > 0 {
+        let previous = start - 1;
+        if tokens.get(previous).is_none_or(|candidate| {
+            candidate.kind != TokenKind::Operator || source[candidate.range] != *"."
+        }) {
+            break;
+        }
+        let Some(segment) = previous.checked_sub(1) else {
+            break;
+        };
+        if tokens.get(segment).is_none_or(|candidate| {
+            !matches!(candidate.kind, TokenKind::Variable | TokenKind::Attribute)
+        }) {
+            break;
+        }
+        start = segment;
+    }
+
+    let end = if inclusive { position + 1 } else { position };
+    tokens
+        .get(start..end.max(start))
+        .unwrap_or_default()
+        .iter()
+        .filter(|candidate| matches!(candidate.kind, TokenKind::Variable | TokenKind::Attribute))
+        .map(|candidate| &source[candidate.range])
+        .collect()
+}
+
+/// the contents of a string literal, its quotes excluded
+fn string_contents(source: &str, range: TextRange) -> TextRange {
+    let text = &source[range];
+    let Some(quote) = text.chars().next() else {
+        return range;
+    };
+    if !matches!(quote, '"' | '\'') {
+        return range;
+    }
+
+    let start = range.start() + TextSize::from(1);
+    let end = if text.len() > 1 && text.ends_with(quote) {
+        range.end() - TextSize::from(1)
+    } else {
+        range.end()
+    };
+
+    TextRange::new(start, end.max(start))
+}
+
+#[cfg(test)]
+mod tests {
+    use crate::django_template::tests::TemplateTest;
+
+    /// the same small django project the completion tests use
+    fn project(template: &str) -> TemplateTest {
+        TemplateTest::new(&[
+            (
+                "blog/models.py",
+                "
+                class Author:
+                    name: str
+
+                class Book:
+                    title: str
+                    author: Author
+                ",
+            ),
+            (
+                "blog/views.py",
+                "
+                from blog.models import Book
+
+                def post(request):
+                    return render(request, 'blog/post.html', {'book': Book()})
+                ",
+            ),
+            (
+                "blog/urls.py",
+                "
+                app_name = 'blog'
+
+                urlpatterns = [path('books/', index, name='index')]
+                ",
+            ),
+            (
+                "blog/templatetags/blog_extras.py",
+                "
+                from django import template
+
+                register = template.Library()
+
+                @register.filter
+                def shout(value):
+                    return value
+
+                @register.simple_tag
+                def book_count():
+                    return 0
+                ",
+            ),
+            (
+                "blog/templates/blog/base.html",
+                "{% block content %}{% endblock %}",
+            ),
+            ("blog/templates/blog/post.html", template),
+        ])
+    }
+
+    #[test]
+    fn extends_navigates_to_the_template_it_names() {
+        let definitions = project("{% extends 'blog/b<CURSOR>ase.html' %}").definitions();
+        assert_eq!(definitions, ["/blog/templates/blog/base.html:"]);
+    }
+
+    #[test]
+    fn include_navigates_to_the_template_it_names() {
+        let definitions = project("{% include 'blog/<CURSOR>base.html' %}").definitions();
+        assert_eq!(definitions, ["/blog/templates/blog/base.html:"]);
+    }
+
+    #[test]
+    fn an_include_with_a_fragment_navigates_to_the_partial_inside_it() {
+        let test = TemplateTest::new(&[
+            (
+                "blog/templates/blog/cards.html",
+                "{% partialdef card %}x{% endpartialdef %}",
+            ),
+            (
+                "blog/templates/blog/post.html",
+                "{% include 'blog/car<CURSOR>ds.html#card' %}",
+            ),
+        ]);
+
+        assert_eq!(test.definitions(), ["/blog/templates/blog/cards.html:card"]);
+    }
+
+    #[test]
+    fn url_navigates_to_the_route_that_is_named() {
+        let definitions = project("{% url 'blog:<CURSOR>index' %}").definitions();
+        assert_eq!(definitions, ["/blog/urls.py:'index'"]);
+    }
+
+    #[test]
+    fn a_filter_navigates_to_the_function_registered_under_it() {
+        let definitions = project("{{ book.title|sh<CURSOR>out }}").definitions();
+        assert_eq!(definitions, ["/blog/templatetags/blog_extras.py:shout"]);
+    }
+
+    #[test]
+    fn a_tag_navigates_to_the_function_registered_under_it() {
+        let definitions = project("{% book_c<CURSOR>ount %}").definitions();
+        assert_eq!(
+            definitions,
+            ["/blog/templatetags/blog_extras.py:book_count"]
+        );
+    }
+
+    #[test]
+    fn a_builtin_tag_navigates_nowhere() {
+        assert!(
+            project("{% ext<CURSOR>ends 'blog/base.html' %}")
+                .definitions()
+                .is_empty()
+        );
+    }
+
+    #[test]
+    fn load_navigates_to_the_library_module() {
+        let definitions = project("{% load blog_ex<CURSOR>tras %}").definitions();
+        assert_eq!(definitions, ["/blog/templatetags/blog_extras.py:"]);
+    }
+
+    #[test]
+    fn a_partial_navigates_to_the_partialdef_that_declares_it() {
+        let definitions =
+            project("{% partialdef card %}x{% endpartialdef %}{% partial ca<CURSOR>rd %}")
+                .definitions();
+        assert_eq!(definitions, ["/blog/templates/blog/post.html:card"]);
+    }
+
+    #[test]
+    fn a_block_in_a_child_navigates_to_the_parents_block() {
+        let definitions =
+            project("{% extends 'blog/base.html' %}{% block con<CURSOR>tent %}{% endblock %}")
+                .definitions();
+        assert_eq!(definitions, ["/blog/templates/blog/base.html:content"]);
+    }
+
+    #[test]
+    fn a_context_variable_navigates_to_the_view_that_supplies_it() {
+        let definitions = project("{{ bo<CURSOR>ok }}").definitions();
+        assert_eq!(definitions, ["/blog/views.py:'book'"]);
+    }
+
+    #[test]
+    fn a_loop_variable_navigates_to_the_tag_that_binds_it() {
+        let definitions =
+            project("{% for entry in shelf %}{{ ent<CURSOR>ry }}{% endfor %}").definitions();
+        assert_eq!(definitions, ["/blog/templates/blog/post.html:entry"]);
+    }
+
+    #[test]
+    fn an_attribute_navigates_to_the_type_it_is_read_off() {
+        let definitions = project("{{ book.au<CURSOR>thor }}").definitions();
+        assert_eq!(definitions, ["/blog/models.py:Book"]);
+    }
+
+    #[test]
+    fn an_unknown_name_navigates_nowhere() {
+        assert!(project("{{ myst<CURSOR>ery }}").definitions().is_empty());
+    }
+
+    #[test]
+    fn a_comment_navigates_nowhere() {
+        assert!(project("{# bo<CURSOR>ok #}").definitions().is_empty());
+    }
+}
diff --git a/crates/ty_ide/src/django_template/index.rs b/crates/ty_ide/src/django_template/index.rs
new file mode 100644
index 0000000000..5e8bff9c47
--- /dev/null
+++ b/crates/ty_ide/src/django_template/index.rs
@@ -0,0 +1,1016 @@
+//! the structure a flat template token stream implies
+//!
+//! block nesting in the django template language is imposed by the tags rather
+//! than by the delimiters: `{% for %}` opens a block only because a matching
+//! `{% endfor %}` closes it. this module replays the construct stream with a
+//! stack to recover that structure, and picks out along the way everything the
+//! ide features need to look up by name — the blocks and partials the template
+//! defines, the templates it extends and includes, the libraries it loads, and
+//! the names its tags bind.
+//!
+//! the index resolves every name it records against the source while it builds,
+//! so nothing downstream needs the source text again to interpret it.
+
+use compact_str::{CompactString, ToCompactString};
+use ruff_text_size::{TextRange, TextSize};
+
+use super::builtins;
+use super::lexer::{Construct, ConstructKind, Lexed, Token, TokenKind, lex};
+
+/// a name a template defines: a `{% block %}` or a `{% partialdef %}`
+#[derive(Debug, Clone, PartialEq, Eq, get_size2::GetSize)]
+pub(crate) struct Definition {
+    pub(crate) name: CompactString,
+    /// the name as written in the opening tag
+    pub(crate) name_range: TextRange,
+    /// the opening tag's `{%` through the closing tag's `%}`, or through the end
+    /// of the template when the block was never closed
+    pub(crate) full_range: TextRange,
+}
+
+/// a reference to another template, from `{% extends %}` or `{% include %}`
+#[derive(Debug, Clone, PartialEq, Eq, get_size2::GetSize)]
+pub(crate) struct TemplateReference {
+    /// the template's path, as the loader will see it
+    pub(crate) name: CompactString,
+    /// the fragment after a `#`, naming a partial inside that template
+    pub(crate) partial: Option<CompactString>,
+    /// the string literal, its quotes excluded
+    pub(crate) range: TextRange,
+}
+
+/// a `{% load %}`ed library
+#[derive(Debug, Clone, PartialEq, Eq, get_size2::GetSize)]
+pub(crate) struct Load {
+    pub(crate) library: CompactString,
+    pub(crate) range: TextRange,
+}
+
+/// where a name bound inside the template came from
+#[derive(Debug, Clone, Copy, PartialEq, Eq, get_size2::GetSize)]
+pub(crate) enum BindingOrigin {
+    /// `{% for book in books %}` — one element of the iterable
+    LoopVariable,
+    /// django's `forloop`, in scope inside every `{% for %}`
+    ForLoop,
+    /// `{% with total=x %}` or a trailing `… as total`
+    Alias,
+}
+
+/// a name a tag binds, and the region of the template it is bound over
+#[derive(Debug, Clone, PartialEq, Eq, get_size2::GetSize)]
+pub(crate) struct Binding {
+    pub(crate) name: CompactString,
+    /// the name as written
+    pub(crate) range: TextRange,
+    /// the region the name is visible in
+    pub(crate) scope: TextRange,
+    pub(crate) origin: BindingOrigin,
+    /// the path the name was bound to, when the tag wrote one
+    ///
+    /// this is what lets `{% with author=book.author %}` carry `book.author`'s
+    /// type onto `author`.
+    pub(crate) value: Option<TextRange>,
+}
+
+/// a block a pair of tags spans
+#[derive(Debug, Clone, PartialEq, Eq, get_size2::GetSize)]
+pub(crate) struct Block {
+    pub(crate) name: CompactString,
+    /// the tag that closes it
+    pub(crate) end_tag: CompactString,
+    /// the opening tag's whole construct
+    pub(crate) open_range: TextRange,
+    /// the opening tag's `{%` through the closing tag's `%}`, or through the end
+    /// of the template when the block was never closed
+    pub(crate) full_range: TextRange,
+    /// what the block encloses: between the two tags, or from the opening tag to
+    /// the end of the template when the block was never closed
+    pub(crate) body_range: TextRange,
+    /// whether the closing tag was actually written
+    pub(crate) closed: bool,
+}
+
+/// a template, lexed and indexed
+#[derive(Debug, PartialEq, Eq, get_size2::GetSize)]
+pub(crate) struct TemplateIndex {
+    lexed: Lexed,
+    extends: Option<TemplateReference>,
+    includes: Vec<TemplateReference>,
+    blocks: Vec<Definition>,
+    partials: Vec<Definition>,
+    loads: Vec<Load>,
+    bindings: Vec<Binding>,
+    spans: Vec<Block>,
+}
+
+impl TemplateIndex {
+    pub(crate) fn from_source(source: &str) -> Self {
+        Builder::new(source).build()
+    }
+
+    pub(crate) fn lexed(&self) -> &Lexed {
+        &self.lexed
+    }
+
+    /// the template this one extends
+    pub(crate) fn extends(&self) -> Option<&TemplateReference> {
+        self.extends.as_ref()
+    }
+
+    /// every template this one includes
+    pub(crate) fn includes(&self) -> &[TemplateReference] {
+        &self.includes
+    }
+
+    /// the `{% block %}`s this template defines, in source order
+    pub(crate) fn blocks(&self) -> &[Definition] {
+        &self.blocks
+    }
+
+    /// the `{% partialdef %}`s this template defines, in source order
+    pub(crate) fn partials(&self) -> &[Definition] {
+        &self.partials
+    }
+
+    pub(crate) fn loads(&self) -> &[Load] {
+        &self.loads
+    }
+
+    /// every name bound by a tag, in source order
+    pub(crate) fn bindings(&self) -> &[Binding] {
+        &self.bindings
+    }
+
+    /// the names in scope at `offset`, in source order
+    pub(crate) fn bindings_at(&self, offset: TextSize) -> impl Iterator<Item = &Binding> {
+        self.bindings
+            .iter()
+            .filter(move |binding| binding.scope.contains_inclusive(offset))
+    }
+
+    /// the binding `name` resolves to at `offset`
+    ///
+    /// the innermost one wins, and since a nested tag is always written after the
+    /// tag enclosing it, that is the last one in source order.
+    pub(crate) fn resolve_binding(&self, name: &str, offset: TextSize) -> Option<&Binding> {
+        self.bindings_at(offset)
+            .filter(|binding| binding.name == name)
+            .last()
+    }
+
+    /// the block tags still open at `offset`, innermost first
+    ///
+    /// this is what tells a completion inside `{% for %}…{% |` that the tag it
+    /// should offer is `endfor`. a cursor in either of the block's own tags is
+    /// not inside it, so `{% endif %}` never offers itself a second time.
+    pub(crate) fn open_blocks_at(&self, offset: TextSize) -> Vec<&Block> {
+        let mut open: Vec<&Block> = self
+            .spans
+            .iter()
+            .filter(|block| block.body_range.contains_inclusive(offset))
+            .collect();
+
+        open.sort_by_key(|block| std::cmp::Reverse(block.open_range.start()));
+        open
+    }
+}
+
+struct Builder<'src> {
+    source: &'src str,
+    lexed: Lexed,
+}
+
+impl<'src> Builder<'src> {
+    fn new(source: &'src str) -> Self {
+        Self {
+            source,
+            lexed: lex(source),
+        }
+    }
+
+    fn build(self) -> TemplateIndex {
+        let end_tags = self.end_tags_present();
+
+        let mut extends = None;
+        let mut includes = Vec::new();
+        let mut blocks = Vec::new();
+        let mut partials = Vec::new();
+        let mut loads = Vec::new();
+        let mut bindings: Vec<Binding> = Vec::new();
+        let mut spans = Vec::new();
+
+        let mut stack: Vec<Frame> = Vec::new();
+        let template_end = TextSize::try_from(self.source.len()).unwrap_or_default();
+
+        for construct in self.lexed.constructs() {
+            if construct.kind != ConstructKind::Tag {
+                continue;
+            }
+            let Some(name_range) = construct.name else {
+                continue;
+            };
+            let name = &self.source[name_range];
+            let arguments = self.arguments(construct);
+
+            // a closing tag ends the innermost block it can close. a stray one
+            // closes nothing rather than unwinding the whole stack, so that a
+            // half-typed template keeps the structure it does have.
+            if let Some(position) = stack.iter().rposition(|frame| frame.end_tag == name) {
+                for frame in stack.split_off(position).into_iter().rev() {
+                    frame.close(
+                        construct.range,
+                        &mut blocks,
+                        &mut partials,
+                        &mut bindings,
+                        &mut spans,
+                    );
+                }
+                continue;
+            }
+
+            match name {
+                "extends" if extends.is_none() => {
+                    extends = arguments
+                        .iter()
+                        .find_map(|token| self.template_reference(token));
+                }
+                "include" => {
+                    if let Some(reference) = arguments
+                        .iter()
+                        .find_map(|token| self.template_reference(token))
+                    {
+                        includes.push(reference);
+                    }
+                }
+                "load" => loads.extend(self.loaded_libraries(arguments)),
+                _ => {}
+            }
+
+            // every name a tag binds starts out scoped to the end of the
+            // template; the enclosing block narrows it when it closes
+            let first_binding = bindings.len();
+            bindings.extend(self.bindings_of(name, arguments, construct, template_end));
+
+            let definition =
+                self.definition_of(name, arguments, construct)
+                    .map(|(kind, definition)| {
+                        let target = match kind {
+                            DefinitionKind::Block => &mut blocks,
+                            DefinitionKind::Partial => &mut partials,
+                        };
+                        target.push(definition);
+                        (kind, target.len() - 1)
+                    });
+
+            let end_tag = builtins::end_tag_for(name)
+                .map(ToCompactString::to_compact_string)
+                .or_else(|| {
+                    // a project's own block tag is recognised by the closing tag
+                    // it is actually paired with in this file. this needs no
+                    // knowledge of the tag's python definition, which is what
+                    // makes unknown libraries behave.
+                    let candidate = format!("end{name}");
+                    end_tags
+                        .contains(&candidate.as_str())
+                        .then(|| candidate.to_compact_string())
+                });
+
+            if let Some(end_tag) = end_tag {
+                stack.push(Frame {
+                    name: name.to_compact_string(),
+                    end_tag,
+                    open_range: construct.range,
+                    definition,
+                    first_binding,
+                });
+            }
+        }
+
+        // whatever is still open runs to the end of the template
+        for frame in std::mem::take(&mut stack).into_iter().rev() {
+            frame.close_unclosed(
+                template_end,
+                &mut blocks,
+                &mut partials,
+                &mut bindings,
+                &mut spans,
+            );
+        }
+
+        spans.sort_by_key(|block| block.open_range.start());
+
+        TemplateIndex {
+            lexed: self.lexed,
+            extends,
+            includes,
+            blocks,
+            partials,
+            loads,
+            bindings,
+            spans,
+        }
+    }
+
+    /// every `end…` tag name written anywhere in the template
+    fn end_tags_present(&self) -> Vec<&'src str> {
+        let mut names: Vec<_> = self
+            .lexed
+            .constructs()
+            .iter()
+            .filter_map(|construct| construct.name)
+            .map(|range| &self.source[range])
+            .filter(|name| name.starts_with("end"))
+            .collect();
+        names.sort_unstable();
+        names.dedup();
+        names
+    }
+
+    /// a construct's tokens with its delimiters and its tag name dropped
+    fn arguments(&self, construct: &Construct) -> &[Token] {
+        let tokens = self.lexed.construct_tokens(construct);
+
+        let start = match tokens
+            .iter()
+            .position(|token| token.kind == TokenKind::TagName)
+        {
+            Some(index) => index + 1,
+            None => tokens
+                .iter()
+                .position(|token| token.kind != TokenKind::Delimiter)
+                .unwrap_or(tokens.len()),
+        };
+        let end = tokens
+            .iter()
+            .rposition(|token| token.kind != TokenKind::Delimiter)
+            .map_or(start, |index| index + 1);
+
+        tokens.get(start..end.max(start)).unwrap_or_default()
+    }
+
+    /// the block or partial `construct` defines
+    fn definition_of(
+        &self,
+        tag: &str,
+        arguments: &[Token],
+        construct: &Construct,
+    ) -> Option<(DefinitionKind, Definition)> {
+        let kind = match tag {
+            "block" => DefinitionKind::Block,
+            "partialdef" => DefinitionKind::Partial,
+            _ => return None,
+        };
+
+        let name_token = arguments
+            .iter()
+            .find(|token| matches!(token.kind, TokenKind::Variable | TokenKind::String))?;
+        let (name, name_range) = self.name_of(name_token)?;
+
+        Some((
+            kind,
+            Definition {
+                name,
+                name_range,
+                full_range: construct.range,
+            },
+        ))
+    }
+
+    /// the template a `{% extends %}`/`{% include %}` argument names
+    fn template_reference(&self, token: &Token) -> Option<TemplateReference> {
+        let (value, range) = self.string_value(token)?;
+        // `template.html#fragment` addresses a partial inside that template
+        let (name, partial) = match value.split_once('#') {
+            Some((name, partial)) => (name, Some(partial.to_compact_string())),
+            None => (value, None),
+        };
+        Some(TemplateReference {
+            name: name.to_compact_string(),
+            partial,
+            range,
+        })
+    }
+
+    /// the libraries a `{% load %}` names
+    ///
+    /// `{% load a b %}` loads two libraries, while `{% load a b from c %}` loads
+    /// only `c` and pulls the names `a` and `b` out of it.
+    fn loaded_libraries(&self, arguments: &[Token]) -> Vec<Load> {
+        let from = arguments.iter().position(|token| {
+            token.kind == TokenKind::Keyword && &self.source[token.range] == "from"
+        });
+
+        let libraries: &[Token] = match from {
+            Some(index) => arguments.get(index + 1..).unwrap_or_default(),
+            None => arguments,
+        };
+
+        libraries
+            .iter()
+            .filter(|token| token.kind == TokenKind::Variable)
+            .map(|token| Load {
+                library: self.source[token.range].to_compact_string(),
+                range: token.range,
+            })
+            .collect()
+    }
+
+    /// the names `construct` binds, scoped to the end of the template
+    ///
+    /// the caller narrows the scope to the enclosing block once its closing tag
+    /// turns up.
+    fn bindings_of(
+        &self,
+        tag: &str,
+        arguments: &[Token],
+        construct: &Construct,
+        scope_end: TextSize,
+    ) -> Vec<Binding> {
+        let mut bindings = Vec::new();
+        let body = TextRange::new(construct.range.end(), scope_end.max(construct.range.end()));
+
+        if tag == "for" {
+            let iterable_start = arguments.iter().position(|token| {
+                token.kind == TokenKind::Keyword && &self.source[token.range] == "in"
+            });
+            let targets = arguments
+                .get(..iterable_start.unwrap_or(arguments.len()))
+                .unwrap_or_default();
+            let iterable = iterable_start.and_then(|index| self.path_at(arguments, index + 1));
+
+            for token in targets
+                .iter()
+                .filter(|token| token.kind == TokenKind::Variable)
+            {
+                bindings.push(Binding {
+                    name: self.source[token.range].to_compact_string(),
+                    range: token.range,
+                    scope: body,
+                    origin: BindingOrigin::LoopVariable,
+                    value: iterable,
+                });
+            }
+
+            bindings.push(Binding {
+                name: "forloop".to_compact_string(),
+                range: construct.name.unwrap_or(construct.range),
+                scope: body,
+                origin: BindingOrigin::ForLoop,
+                value: None,
+            });
+        }
+
+        // `{% with total=x %}` binds over its block. `{% include … with x=y %}`
+        // binds only inside the included template, so it must not appear here.
+        if matches!(tag, "with" | "blocktranslate" | "blocktrans") {
+            for (index, token) in arguments.iter().enumerate() {
+                if token.kind != TokenKind::KeywordArgument {
+                    continue;
+                }
+                bindings.push(Binding {
+                    name: self.source[token.range].to_compact_string(),
+                    range: token.range,
+                    scope: body,
+                    origin: BindingOrigin::Alias,
+                    // skip the `=` to reach the value
+                    value: self.path_at(arguments, index + 2),
+                });
+            }
+        }
+
+        // a trailing `… as name` binds in every tag that has one
+        if let Some(index) = arguments.iter().rposition(|token| {
+            token.kind == TokenKind::Keyword && &self.source[token.range] == "as"
+        }) && let Some(target) = arguments.get(index + 1)
+            && target.kind == TokenKind::Variable
+        {
+            // `{% with x as total %}` writes the value first, unlike every other
+            // tag, whose `as` target names the tag's own result
+            let value = (tag == "with")
+                .then(|| self.path_at(arguments, 0))
+                .flatten();
+
+            bindings.push(Binding {
+                name: self.source[target.range].to_compact_string(),
+                range: target.range,
+                scope: body,
+                origin: BindingOrigin::Alias,
+                value,
+            });
+        }
+
+        bindings
+    }
+
+    /// the whole dotted path starting at `index`, as in `book.author.name`
+    fn path_at(&self, arguments: &[Token], index: usize) -> Option<TextRange> {
+        let first = arguments.get(index)?;
+        if !matches!(
+            first.kind,
+            TokenKind::Variable | TokenKind::String | TokenKind::Number
+        ) {
+            return None;
+        }
+
+        let mut end = first.range.end();
+        let mut cursor = index + 1;
+        while let (Some(dot), Some(segment)) = (arguments.get(cursor), arguments.get(cursor + 1)) {
+            if dot.kind != TokenKind::Operator
+                || &self.source[dot.range] != "."
+                || segment.kind != TokenKind::Attribute
+            {
+                break;
+            }
+            end = segment.range.end();
+            cursor += 2;
+        }
+
+        Some(TextRange::new(first.range.start(), end))
+    }
+
+    /// a name written either bare or as a string literal
+    fn name_of(&self, token: &Token) -> Option<(CompactString, TextRange)> {
+        match token.kind {
+            TokenKind::String => self
+                .string_value(token)
+                .map(|(value, range)| (value.to_compact_string(), range)),
+            _ => Some((self.source[token.range].to_compact_string(), token.range)),
+        }
+    }
+
+    /// the contents of a string literal, and its range with the quotes excluded
+    fn string_value(&self, token: &Token) -> Option<(&'src str, TextRange)> {
+        if token.kind != TokenKind::String {
+            return None;
+        }
+
+        let text = &self.source[token.range];
+        let quote = text.chars().next()?;
+        if !matches!(quote, '"' | '\'') {
+            return None;
+        }
+
+        let start = token.range.start() + TextSize::from(1);
+        // an unterminated literal still names a template: the user is mid-typing
+        let end = if text.len() > 1 && text.ends_with(quote) {
+            token.range.end() - TextSize::from(1)
+        } else {
+            token.range.end()
+        };
+
+        let range = TextRange::new(start, end.max(start));
+        Some((&self.source[range], range))
+    }
+}
+
+#[derive(Debug, Clone, Copy)]
+enum DefinitionKind {
+    Block,
+    Partial,
+}
+
+/// an open block, and everything whose extent its closing tag settles
+///
+/// the definition the block declares and the bindings made inside it are already
+/// recorded, in declaration order; the frame only remembers where they are so it
+/// can trim their extents down to the block when the closing tag turns up.
+struct Frame {
+    name: CompactString,
+    end_tag: CompactString,
+    open_range: TextRange,
+    definition: Option<(DefinitionKind, usize)>,
+    first_binding: usize,
+}
+
+impl Frame {
+    /// close the block at the `{% end… %}` tag spanning `close_range`
+    fn close(
+        self,
+        close_range: TextRange,
+        blocks: &mut [Definition],
+        partials: &mut [Definition],
+        bindings: &mut [Binding],
+        spans: &mut Vec<Block>,
+    ) {
+        let body_range = TextRange::new(
+            self.open_range.end(),
+            close_range.start().max(self.open_range.end()),
+        );
+        self.finish(
+            close_range.end(),
+            body_range,
+            true,
+            blocks,
+            partials,
+            bindings,
+            spans,
+        );
+    }
+
+    /// close a block whose `{% end… %}` tag was never written
+    fn close_unclosed(
+        self,
+        template_end: TextSize,
+        blocks: &mut [Definition],
+        partials: &mut [Definition],
+        bindings: &mut [Binding],
+        spans: &mut Vec<Block>,
+    ) {
+        let end = template_end.max(self.open_range.end());
+        let body_range = TextRange::new(self.open_range.end(), end);
+        self.finish(end, body_range, false, blocks, partials, bindings, spans);
+    }
+
+    #[expect(
+        clippy::too_many_arguments,
+        reason = "the four output collections are the frame's whole purpose; bundling them into a \
+                  struct would only rename them"
+    )]
+    fn finish(
+        self,
+        end: TextSize,
+        body_range: TextRange,
+        closed: bool,
+        blocks: &mut [Definition],
+        partials: &mut [Definition],
+        bindings: &mut [Binding],
+        spans: &mut Vec<Block>,
+    ) {
+        let full_range = TextRange::new(self.open_range.start(), end.max(self.open_range.end()));
+
+        if let Some((kind, index)) = self.definition {
+            let definition = match kind {
+                DefinitionKind::Block => &mut blocks[index],
+                DefinitionKind::Partial => &mut partials[index],
+            };
+            definition.full_range = full_range;
+        }
+
+        // a binding declared inside this block dies with it — at the closing tag
+        // rather than after it, so that a cursor on the `{% endfor %}`'s heels no
+        // longer sees the loop variable. an inner block has already trimmed its
+        // own bindings to something tighter, so this only ever narrows.
+        for binding in &mut bindings[self.first_binding..] {
+            let scope_end = binding
+                .scope
+                .end()
+                .min(body_range.end())
+                .max(binding.scope.start());
+            binding.scope = TextRange::new(binding.scope.start(), scope_end);
+        }
+
+        spans.push(Block {
+            name: self.name,
+            end_tag: self.end_tag,
+            open_range: self.open_range,
+            full_range,
+            body_range,
+            closed,
+        });
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use ruff_text_size::TextSize;
+
+    use super::{BindingOrigin, TemplateIndex};
+
+    fn index(source: &str) -> TemplateIndex {
+        TemplateIndex::from_source(source)
+    }
+
+    fn offset_of(source: &str, needle: &str) -> TextSize {
+        TextSize::try_from(source.find(needle).expect("needle to be in the source")).unwrap()
+    }
+
+    #[test]
+    fn extends_and_includes() {
+        let source = "{% extends 'base.html' %}{% include \"card.html\" %}{% include x %}";
+        let index = index(source);
+
+        assert_eq!(
+            index.extends().map(|reference| reference.name.as_str()),
+            Some("base.html")
+        );
+        assert_eq!(
+            index
+                .includes()
+                .iter()
+                .map(|reference| reference.name.as_str())
+                .collect::<Vec<_>>(),
+            ["card.html"],
+            "a variable include names no template statically"
+        );
+    }
+
+    #[test]
+    fn a_reference_can_address_a_partial_inside_a_template() {
+        let index = index("{% include 'blog.html#comment-item' %}");
+        let reference = &index.includes()[0];
+        assert_eq!(reference.name, "blog.html");
+        assert_eq!(reference.partial.as_deref(), Some("comment-item"));
+    }
+
+    #[test]
+    fn a_reference_range_excludes_the_quotes() {
+        let source = "{% extends 'base.html' %}";
+        let index = index(source);
+        assert_eq!(&source[index.extends().unwrap().range], "base.html");
+    }
+
+    #[test]
+    fn blocks_span_from_their_opening_tag_to_their_closing_one() {
+        let source = "{% block content %}hi{% endblock %}";
+        let index = index(source);
+
+        let block = &index.blocks()[0];
+        assert_eq!(block.name, "content");
+        assert_eq!(&source[block.name_range], "content");
+        assert_eq!(&source[block.full_range], source);
+    }
+
+    #[test]
+    fn an_unclosed_block_runs_to_the_end_of_the_template() {
+        let source = "{% block content %}hi";
+        let index = index(source);
+        assert_eq!(&source[index.blocks()[0].full_range], source);
+    }
+
+    #[test]
+    fn nested_blocks_are_all_recorded() {
+        let source = "{% block outer %}{% block inner %}{% endblock %}{% endblock %}";
+        let index = index(source);
+        assert_eq!(
+            index
+                .blocks()
+                .iter()
+                .map(|block| block.name.as_str())
+                .collect::<Vec<_>>(),
+            ["outer", "inner"]
+        );
+    }
+
+    #[test]
+    fn partials_are_kept_apart_from_blocks() {
+        let source = "{% partialdef card inline %}x{% endpartialdef %}{% block b %}{% endblock %}";
+        let index = index(source);
+
+        assert_eq!(
+            index
+                .partials()
+                .iter()
+                .map(|partial| partial.name.as_str())
+                .collect::<Vec<_>>(),
+            ["card"]
+        );
+        assert_eq!(
+            index
+                .blocks()
+                .iter()
+                .map(|block| block.name.as_str())
+                .collect::<Vec<_>>(),
+            ["b"]
+        );
+    }
+
+    #[test]
+    fn loads() {
+        let index = index("{% load static i18n %}{% load humanize %}");
+        assert_eq!(
+            index
+                .loads()
+                .iter()
+                .map(|load| load.library.as_str())
+                .collect::<Vec<_>>(),
+            ["static", "i18n", "humanize"]
+        );
+    }
+
+    #[test]
+    fn load_from_names_only_the_library_it_pulls_from() {
+        let index = index("{% load bar baz from foo %}");
+        assert_eq!(
+            index
+                .loads()
+                .iter()
+                .map(|load| load.library.as_str())
+                .collect::<Vec<_>>(),
+            ["foo"]
+        );
+    }
+
+    #[test]
+    fn a_for_loop_binds_its_targets_and_forloop_over_its_body() {
+        let source = "{% for book in books %}x{% endfor %}after";
+        let index = index(source);
+
+        let inside = offset_of(source, "x");
+        let names: Vec<_> = index
+            .bindings_at(inside)
+            .map(|binding| binding.name.as_str())
+            .collect();
+        assert_eq!(names, ["book", "forloop"]);
+
+        let after = offset_of(source, "after");
+        assert_eq!(index.bindings_at(after).count(), 0);
+    }
+
+    #[test]
+    fn a_loop_binding_remembers_the_whole_iterable_path() {
+        let source = "{% for book in shelf.books.all %}x{% endfor %}";
+        let index = index(source);
+
+        let binding = index
+            .bindings()
+            .iter()
+            .find(|binding| binding.name == "book")
+            .unwrap();
+        assert_eq!(binding.origin, BindingOrigin::LoopVariable);
+        assert_eq!(
+            binding.value.map(|range| &source[range]),
+            Some("shelf.books.all")
+        );
+    }
+
+    #[test]
+    fn unpacking_a_loop_binds_every_target() {
+        let source = "{% for key, value in mapping.items %}x{% endfor %}";
+        let index = index(source);
+
+        let names: Vec<_> = index
+            .bindings_at(offset_of(source, "x"))
+            .map(|binding| binding.name.as_str())
+            .collect();
+        assert_eq!(names, ["key", "value", "forloop"]);
+    }
+
+    #[test]
+    fn with_binds_each_of_its_keyword_arguments() {
+        let source = "{% with total=cart.total name=user.name %}x{% endwith %}";
+        let index = index(source);
+
+        let bindings: Vec<_> = index
+            .bindings_at(offset_of(source, "x"))
+            .map(|binding| {
+                (
+                    binding.name.as_str(),
+                    binding.value.map(|range| &source[range]),
+                )
+            })
+            .collect();
+        assert_eq!(
+            bindings,
+            [("total", Some("cart.total")), ("name", Some("user.name"))]
+        );
+    }
+
+    #[test]
+    fn the_older_with_spelling_writes_its_value_first() {
+        let source = "{% with cart.total as total %}x{% endwith %}";
+        let index = index(source);
+
+        let binding = index
+            .resolve_binding("total", offset_of(source, "x"))
+            .unwrap();
+        assert_eq!(
+            binding.value.map(|range| &source[range]),
+            Some("cart.total")
+        );
+    }
+
+    #[test]
+    fn a_trailing_as_binds_the_tag_result() {
+        let source = "{% url 'detail' pk=1 as detail_url %}{{ detail_url }}";
+        let index = index(source);
+
+        let names: Vec<_> = index
+            .bindings_at(offset_of(source, "{{ detail_url"))
+            .map(|binding| binding.name.as_str())
+            .collect();
+        assert_eq!(names, ["detail_url"]);
+    }
+
+    #[test]
+    fn an_as_binding_inside_a_block_does_not_escape_it() {
+        let source = "{% if x %}{% url 'a' as u %}in{% endif %}out";
+        let index = index(source);
+
+        assert_eq!(index.bindings_at(offset_of(source, "in")).count(), 1);
+        assert_eq!(index.bindings_at(offset_of(source, "out")).count(), 0);
+    }
+
+    #[test]
+    fn an_inner_binding_shadows_an_outer_one() {
+        let source = "{% for x in a %}{% for x in b %}HERE{% endfor %}{% endfor %}";
+        let index = index(source);
+
+        let binding = index
+            .resolve_binding("x", offset_of(source, "HERE"))
+            .unwrap();
+        assert_eq!(binding.value.map(|range| &source[range]), Some("b"));
+    }
+
+    #[test]
+    fn open_blocks_are_reported_innermost_first() {
+        let source = "{% for a in b %}{% if c %}HERE{% endif %}{% endfor %}";
+        let index = index(source);
+
+        assert_eq!(
+            index
+                .open_blocks_at(offset_of(source, "HERE"))
+                .iter()
+                .map(|block| (block.name.as_str(), block.end_tag.as_str()))
+                .collect::<Vec<_>>(),
+            [("if", "endif"), ("for", "endfor")]
+        );
+    }
+
+    #[test]
+    fn a_closed_block_is_no_longer_open() {
+        let source = "{% if c %}{% endif %}HERE";
+        let index = index(source);
+        assert!(index.open_blocks_at(offset_of(source, "HERE")).is_empty());
+    }
+
+    #[test]
+    fn an_unclosed_block_is_open_for_the_rest_of_the_template() {
+        let source = "{% if c %}HERE";
+        let index = index(source);
+
+        let open = index.open_blocks_at(offset_of(source, "HERE"));
+        assert_eq!(open.len(), 1);
+        assert!(!open[0].closed);
+    }
+
+    #[test]
+    fn a_project_block_tag_is_recognised_by_the_end_tag_it_is_paired_with() {
+        // `{% modal %}` is nobody's builtin; the `{% endmodal %}` in the file is
+        // the only evidence that it opens a block, and it is enough
+        let source = "{% modal %}HERE{% endmodal %}";
+        let index = index(source);
+
+        assert_eq!(
+            index
+                .open_blocks_at(offset_of(source, "HERE"))
+                .iter()
+                .map(|block| block.name.as_str())
+                .collect::<Vec<_>>(),
+            ["modal"]
+        );
+    }
+
+    #[test]
+    fn a_tag_with_no_matching_end_tag_opens_no_block() {
+        let source = "{% csrf_token %}HERE";
+        let index = index(source);
+        assert!(index.open_blocks_at(offset_of(source, "HERE")).is_empty());
+    }
+
+    #[test]
+    fn a_stray_closing_tag_closes_nothing() {
+        let source = "{% for a in b %}{% endwith %}HERE{% endfor %}";
+        let index = index(source);
+
+        assert_eq!(
+            index
+                .open_blocks_at(offset_of(source, "HERE"))
+                .iter()
+                .map(|block| block.name.as_str())
+                .collect::<Vec<_>>(),
+            ["for"]
+        );
+    }
+
+    #[test]
+    fn a_branch_tag_does_not_close_its_block() {
+        let source = "{% if a %}{% else %}HERE{% endif %}";
+        let index = index(source);
+
+        assert_eq!(
+            index
+                .open_blocks_at(offset_of(source, "HERE"))
+                .iter()
+                .map(|block| block.name.as_str())
+                .collect::<Vec<_>>(),
+            ["if"]
+        );
+    }
+
+    #[test]
+    fn a_quoted_block_name_is_unquoted() {
+        let source = "{% block \"content\" %}{% endblock %}";
+        let index = index(source);
+        assert_eq!(index.blocks()[0].name, "content");
+        assert_eq!(&source[index.blocks()[0].name_range], "content");
+    }
+
+    #[test]
+    fn an_empty_template_indexes_to_nothing() {
+        let index = index("");
+        assert!(index.blocks().is_empty());
+        assert!(index.bindings().is_empty());
+        assert!(index.extends().is_none());
+    }
+}
diff --git a/crates/ty_ide/src/django_template/lexer.rs b/crates/ty_ide/src/django_template/lexer.rs
new file mode 100644
index 0000000000..7ab6773aaf
--- /dev/null
+++ b/crates/ty_ide/src/django_template/lexer.rs
@@ -0,0 +1,917 @@
+//! a lexer for the django template language
+//!
+//! the language is not a nested grammar the way python is: a template is a flat
+//! sequence of literal text and three kinds of construct — `{{ variable }}`,
+//! `{% tag %}` and `{# comment #}`. block structure (`{% if %}` … `{% endif %}`)
+//! is imposed *by the tags themselves*, not by the lexer, which is why this
+//! module stops at a flat token stream and leaves nesting to [`super::index`].
+//!
+//! the lexer is written for an editor rather than for a renderer, so it is
+//! deliberately tolerant: a construct whose closing delimiter the user has not
+//! typed yet still lexes, so that completions fire inside it. to keep the damage
+//! from a stray `{%` local, an unterminated construct ends at the end of its line
+//! rather than swallowing the rest of the file.
+
+use std::ops::Range;
+
+use ruff_text_size::{TextLen, TextRange, TextSize};
+
+/// the classification the lexer gives a run of source text
+///
+/// tokens never overlap and are emitted in source order. everything outside a
+/// construct is covered, as [`TokenKind::Text`]; inside one, only the whitespace
+/// separating the tokens is left out, since nothing wants to highlight it.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, get_size2::GetSize)]
+pub(crate) enum TokenKind {
+    /// literal text, outside any construct
+    Text,
+    /// `{{`, `}}`, `{%`, `%}`, `{#` or `#}`
+    Delimiter,
+    /// the body of a `{# … #}` or of a `{% comment %}` block
+    Comment,
+    /// the name directly after `{%`
+    TagName,
+    /// the name directly after a `|`
+    FilterName,
+    /// the first segment of a variable path
+    Variable,
+    /// a segment of a variable path after a `.`
+    Attribute,
+    /// the name before a `=`, i.e. a tag's keyword argument
+    KeywordArgument,
+    /// a contextual keyword such as `in`, `as` or `only`
+    Keyword,
+    /// `True`, `False` or `None`
+    BuiltinConstant,
+    String,
+    Number,
+    /// `|`, `:`, `=`, `.` and the comparison operators
+    Operator,
+    /// text the lexer could not classify
+    Unknown,
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, get_size2::GetSize)]
+pub(crate) struct Token {
+    pub(crate) kind: TokenKind,
+    pub(crate) range: TextRange,
+}
+
+/// which of the three delimiter pairs a construct is written with
+#[derive(Debug, Clone, Copy, PartialEq, Eq, get_size2::GetSize)]
+pub(crate) enum ConstructKind {
+    /// `{{ … }}`
+    Variable,
+    /// `{% … %}`
+    Tag,
+    /// `{# … #}`
+    Comment,
+}
+
+/// one `{{ … }}`, `{% … %}` or `{# … #}` occurrence
+#[derive(Debug, Clone, PartialEq, Eq, get_size2::GetSize)]
+pub(crate) struct Construct {
+    pub(crate) kind: ConstructKind,
+    /// the whole construct, delimiters included
+    pub(crate) range: TextRange,
+    /// the tag name, for a [`ConstructKind::Tag`] whose name the user has typed
+    pub(crate) name: Option<TextRange>,
+    /// the construct's tokens, as indices into [`Lexed::tokens`]
+    ///
+    /// the opening and closing delimiters are included, so that highlighting can
+    /// work off this slice alone.
+    pub(crate) tokens: Range<usize>,
+    /// whether the closing delimiter was found
+    pub(crate) terminated: bool,
+}
+
+impl Construct {
+    /// the tag name, or `""` for a construct that has none
+    #[cfg(test)]
+    pub(crate) fn name<'src>(&self, source: &'src str) -> &'src str {
+        self.name.map_or("", |range| &source[range])
+    }
+}
+
+/// the result of lexing a whole template
+#[derive(Debug, Default, PartialEq, Eq, get_size2::GetSize)]
+pub(crate) struct Lexed {
+    tokens: Vec<Token>,
+    constructs: Vec<Construct>,
+}
+
+impl Lexed {
+    pub(crate) fn tokens(&self) -> &[Token] {
+        &self.tokens
+    }
+
+    pub(crate) fn constructs(&self) -> &[Construct] {
+        &self.constructs
+    }
+
+    /// the tokens belonging to `construct`, delimiters included
+    pub(crate) fn construct_tokens(&self, construct: &Construct) -> &[Token] {
+        &self.tokens[construct.tokens.clone()]
+    }
+
+    /// the construct `offset` sits in
+    ///
+    /// the end of a construct counts as inside it: a cursor written as
+    /// `{% extends <CURSOR>%}` is at the boundary of the space token, and a
+    /// cursor at the very end of an unterminated `{% extends ` is at the
+    /// boundary of the construct itself.
+    pub(crate) fn construct_at(&self, offset: TextSize) -> Option<&Construct> {
+        let index = self
+            .constructs
+            .partition_point(|construct| construct.range.end() < offset);
+        let construct = self.constructs.get(index)?;
+        (construct.range.start() <= offset).then_some(construct)
+    }
+}
+
+/// lex `source` as a django template
+pub(crate) fn lex(source: &str) -> Lexed {
+    Lexer::new(source).lex()
+}
+
+/// the tags whose body is not template source and so is lexed verbatim
+///
+/// each entry pairs the opening tag with the closing tag that ends the raw run.
+/// `comment` bodies are highlighted as comments; `verbatim` bodies are literal
+/// output and highlighted as text.
+const RAW_BODY_TAGS: &[(&str, &str, TokenKind)] = &[
+    ("comment", "endcomment", TokenKind::Comment),
+    ("verbatim", "endverbatim", TokenKind::Text),
+];
+
+/// names the template language gives a meaning of their own wherever they appear
+/// in a tag's arguments
+///
+/// django has no keyword list — every tag parses its own arguments — so this is
+/// the union over the builtin tags of the words that are syntax rather than
+/// values. highlighting a word from this list inside a tag that doesn't use it
+/// is the one cost, and it is much cheaper than teaching the lexer every tag's
+/// individual grammar.
+///
+/// words django does use as syntax but that read as ordinary variable names —
+/// `{% blocktranslate %}`'s `count` and `context`, `{% ifchanged %}`'s `silent` —
+/// are deliberately left out: wrongly highlighting `{{ count }}` in every template
+/// that has one costs far more than highlighting one argument of one rare tag.
+const KEYWORDS: &[&str] = &[
+    "and", "as", "asvar", "by", "from", "in", "inline", "is", "not", "off", "on", "only", "or",
+    "reversed", "trimmed", "with",
+];
+
+struct Lexer<'src> {
+    source: &'src str,
+    offset: usize,
+    tokens: Vec<Token>,
+    constructs: Vec<Construct>,
+}
+
+impl<'src> Lexer<'src> {
+    fn new(source: &'src str) -> Self {
+        Self {
+            source,
+            offset: 0,
+            tokens: Vec::new(),
+            constructs: Vec::new(),
+        }
+    }
+
+    fn lex(mut self) -> Lexed {
+        while self.offset < self.source.len() {
+            let Some(open) = self.next_construct_start() else {
+                self.push_text_to(self.source.len());
+                break;
+            };
+
+            self.push_text_to(open);
+            self.offset = open;
+            self.lex_construct();
+        }
+
+        Lexed {
+            tokens: self.tokens,
+            constructs: self.constructs,
+        }
+    }
+
+    /// the offset of the next `{{`, `{%` or `{#`, searching from the cursor
+    fn next_construct_start(&self) -> Option<usize> {
+        let rest = &self.source[self.offset..];
+        memchr::memchr_iter(b'{', rest.as_bytes())
+            .find(|&candidate| {
+                matches!(rest.as_bytes().get(candidate + 1), Some(b'{' | b'%' | b'#'))
+            })
+            .map(|candidate| self.offset + candidate)
+    }
+
+    fn lex_construct(&mut self) {
+        let start = self.offset;
+        let (kind, close) = match self.source.as_bytes()[start + 1] {
+            b'{' => (ConstructKind::Variable, "}}"),
+            b'%' => (ConstructKind::Tag, "%}"),
+            _ => (ConstructKind::Comment, "#}"),
+        };
+
+        let first_token = self.tokens.len();
+        self.push_token(TokenKind::Delimiter, start, start + 2);
+        self.offset = start + 2;
+
+        let (body_end, terminated) = self.find_close(close);
+
+        let name = match kind {
+            ConstructKind::Comment => {
+                self.push_token(TokenKind::Comment, self.offset, body_end);
+                None
+            }
+            ConstructKind::Variable => {
+                self.lex_expression(body_end, false);
+                None
+            }
+            ConstructKind::Tag => self.lex_expression(body_end, true),
+        };
+
+        self.offset = body_end;
+        if terminated {
+            self.push_token(TokenKind::Delimiter, body_end, body_end + close.len());
+            self.offset = body_end + close.len();
+        }
+
+        self.constructs.push(Construct {
+            kind,
+            range: self.range(start, self.offset),
+            name,
+            tokens: first_token..self.tokens.len(),
+            terminated,
+        });
+
+        if kind == ConstructKind::Tag {
+            self.lex_raw_body(name);
+        }
+    }
+
+    /// the offset of `close` searching from the cursor, and whether it was found
+    ///
+    /// an unterminated construct is cut off at the end of its line so that a
+    /// stray `{%` costs the user one line of highlighting rather than the whole
+    /// rest of the file.
+    fn find_close(&self, close: &str) -> (usize, bool) {
+        let rest = &self.source[self.offset..];
+        match rest.find(close) {
+            Some(index) => (self.offset + index, true),
+            None => {
+                let line_end = rest.find('\n').map_or(self.source.len(), |index| {
+                    let end = self.offset + index;
+                    // keep a `\r\n` terminator out of the construct
+                    if self.source[..end].ends_with('\r') {
+                        end - 1
+                    } else {
+                        end
+                    }
+                });
+                (line_end, false)
+            }
+        }
+    }
+
+    /// lex the inside of a `{{ … }}` or `{% … %}`, up to `end`
+    ///
+    /// returns the range of the tag name when `expect_tag_name` is set and a name
+    /// is actually there.
+    fn lex_expression(&mut self, end: usize, expect_tag_name: bool) -> Option<TextRange> {
+        let mut tag_name = None;
+        // the previous token is re-classified when what follows reveals its role:
+        // a `|` makes the next name a filter, a `.` makes it an attribute, and a
+        // `=` makes the *preceding* name a keyword argument.
+        let mut after_pipe = false;
+        let mut after_dot = false;
+
+        while self.offset < end {
+            let byte = self.source.as_bytes()[self.offset];
+
+            if byte.is_ascii_whitespace() {
+                self.offset += 1;
+                after_pipe = false;
+                after_dot = false;
+                continue;
+            }
+
+            let start = self.offset;
+
+            match byte {
+                b'"' | b'\'' => {
+                    self.lex_string(byte, end);
+                    self.push_token(TokenKind::String, start, self.offset);
+                }
+                b'|' => {
+                    self.offset += 1;
+                    self.push_token(TokenKind::Operator, start, self.offset);
+                    after_pipe = true;
+                    continue;
+                }
+                b'.' => {
+                    self.offset += 1;
+                    self.push_token(TokenKind::Operator, start, self.offset);
+                    after_dot = true;
+                    continue;
+                }
+                b':' | b',' => {
+                    self.offset += 1;
+                    self.push_token(TokenKind::Operator, start, self.offset);
+                }
+                b'=' | b'!' | b'<' | b'>' => {
+                    self.offset += 1;
+                    let two_byte_operator = self.source.as_bytes().get(self.offset) == Some(&b'=')
+                        || (byte == b'<' && self.source.as_bytes().get(self.offset) == Some(&b'>'));
+                    if two_byte_operator && self.offset < end {
+                        self.offset += 1;
+                    } else if byte == b'=' {
+                        // a lone `=` binds the name before it as a keyword argument
+                        self.reclassify_last(TokenKind::Variable, TokenKind::KeywordArgument);
+                    }
+                    self.push_token(TokenKind::Operator, start, self.offset);
+                }
+                b'-' | b'0'..=b'9' if !after_dot => {
+                    if self.lex_number(end) {
+                        self.push_token(TokenKind::Number, start, self.offset);
+                    } else {
+                        self.offset += 1;
+                        self.push_token(TokenKind::Unknown, start, self.offset);
+                    }
+                }
+                _ => {
+                    let is_name = self.lex_name(end, after_dot);
+                    if !is_name {
+                        self.bump_char();
+                        self.push_token(TokenKind::Unknown, start, self.offset);
+                        after_pipe = false;
+                        after_dot = false;
+                        continue;
+                    }
+
+                    let text = &self.source[start..self.offset];
+                    let kind = if expect_tag_name && tag_name.is_none() {
+                        tag_name = Some(self.range(start, self.offset));
+                        TokenKind::TagName
+                    } else if after_pipe {
+                        TokenKind::FilterName
+                    } else if after_dot {
+                        TokenKind::Attribute
+                    } else if matches!(text, "True" | "False" | "None") {
+                        TokenKind::BuiltinConstant
+                    } else if KEYWORDS.contains(&text) {
+                        TokenKind::Keyword
+                    } else {
+                        TokenKind::Variable
+                    };
+                    self.push_token(kind, start, self.offset);
+                }
+            }
+
+            after_pipe = false;
+            after_dot = false;
+        }
+
+        // a construct the user is still typing can leave the cursor past `end`
+        self.offset = end;
+        tag_name
+    }
+
+    /// consume a quoted string, stopping at the closing quote or at `end`
+    fn lex_string(&mut self, quote: u8, end: usize) {
+        self.offset += 1;
+        while self.offset < end {
+            match self.source.as_bytes()[self.offset] {
+                b'\\' if self.offset + 1 < end => self.offset += 2,
+                byte if byte == quote => {
+                    self.offset += 1;
+                    return;
+                }
+                _ => self.bump_char(),
+            }
+        }
+    }
+
+    /// consume a numeric literal, returning whether one was actually there
+    ///
+    /// a `-` that isn't followed by a digit is not a number: django has no
+    /// arithmetic, so it is a stray character.
+    fn lex_number(&mut self, end: usize) -> bool {
+        let start = self.offset;
+        if self.source.as_bytes()[self.offset] == b'-' {
+            self.offset += 1;
+        }
+
+        let digits = self.consume_while(end, u8::is_ascii_digit);
+        if !digits {
+            self.offset = start;
+            return false;
+        }
+
+        if self.source.as_bytes().get(self.offset) == Some(&b'.')
+            && self
+                .source
+                .as_bytes()
+                .get(self.offset + 1)
+                .is_some_and(u8::is_ascii_digit)
+        {
+            self.offset += 1;
+            self.consume_while(end, u8::is_ascii_digit);
+        }
+
+        if matches!(self.source.as_bytes().get(self.offset), Some(b'e' | b'E')) {
+            let exponent = self.offset;
+            self.offset += 1;
+            if matches!(self.source.as_bytes().get(self.offset), Some(b'+' | b'-')) {
+                self.offset += 1;
+            }
+            if !self.consume_while(end, u8::is_ascii_digit) {
+                self.offset = exponent;
+            }
+        }
+
+        true
+    }
+
+    /// consume a name, returning whether one was actually there
+    ///
+    /// a name after a `.` may start with a digit, because `{{ row.0 }}` indexes a
+    /// sequence. `-` is a name character but never a leading one, so that the
+    /// dashed names partials are conventionally given lex as one token.
+    fn lex_name(&mut self, end: usize, after_dot: bool) -> bool {
+        let start = self.offset;
+        let first = self.source[self.offset..end].chars().next();
+        let is_start = first.is_some_and(|char| {
+            char.is_alphabetic() || char == '_' || (after_dot && char.is_numeric())
+        });
+        if !is_start {
+            return false;
+        }
+
+        while self.offset < end {
+            let Some(char) = self.source[self.offset..end].chars().next() else {
+                break;
+            };
+            if char.is_alphanumeric() || char == '_' || char == '-' {
+                self.offset += char.len_utf8();
+            } else {
+                break;
+            }
+        }
+
+        // a trailing `-` belongs to whatever follows, not to the name
+        while self.source[start..self.offset].ends_with('-') {
+            self.offset -= 1;
+        }
+
+        true
+    }
+
+    /// lex the verbatim body a `{% comment %}` or `{% verbatim %}` tag opens
+    fn lex_raw_body(&mut self, name: Option<TextRange>) {
+        let Some(name) = name else { return };
+        let Some(&(_, end_tag, body_kind)) = RAW_BODY_TAGS
+            .iter()
+            .find(|(open, _, _)| *open == &self.source[name])
+        else {
+            return;
+        };
+
+        let body_start = self.offset;
+        let Some(body_end) = self.find_end_tag(end_tag) else {
+            // an unterminated raw body is *not* swallowed to the end of the file:
+            // leaving the rest of the template to lex normally is far more useful
+            // while the user is still typing the closing tag.
+            return;
+        };
+
+        if body_end > body_start {
+            self.push_token(body_kind, body_start, body_end);
+        }
+        self.offset = body_end;
+    }
+
+    /// the offset of the `{%` opening the next `{% end… %}` tag named `end_tag`
+    fn find_end_tag(&self, end_tag: &str) -> Option<usize> {
+        let mut search = self.offset;
+        while let Some(index) = self.source[search..].find("{%") {
+            let open = search + index;
+            let close = self.source[open..].find("%}").map(|index| open + index)?;
+            if self.source[open + 2..close].split_whitespace().next() == Some(end_tag) {
+                return Some(open);
+            }
+            search = close + 2;
+        }
+        None
+    }
+
+    fn consume_while(&mut self, end: usize, predicate: impl Fn(&u8) -> bool) -> bool {
+        let start = self.offset;
+        while self.offset < end && predicate(&self.source.as_bytes()[self.offset]) {
+            self.offset += 1;
+        }
+        self.offset > start
+    }
+
+    /// advance one character, so that the cursor never lands inside a code point
+    fn bump_char(&mut self) {
+        let width = self.source[self.offset..]
+            .chars()
+            .next()
+            .map_or(1, char::len_utf8);
+        self.offset += width;
+    }
+
+    fn push_text_to(&mut self, end: usize) {
+        if end > self.offset {
+            self.push_token(TokenKind::Text, self.offset, end);
+            self.offset = end;
+        }
+    }
+
+    fn push_token(&mut self, kind: TokenKind, start: usize, end: usize) {
+        if end > start {
+            self.tokens.push(Token {
+                kind,
+                range: self.range(start, end),
+            });
+        }
+    }
+
+    /// re-classify the token just pushed, when a later character reveals its role
+    fn reclassify_last(&mut self, from: TokenKind, to: TokenKind) {
+        if let Some(last) = self.tokens.last_mut()
+            && last.kind == from
+        {
+            last.kind = to;
+        }
+    }
+
+    fn range(&self, start: usize, end: usize) -> TextRange {
+        debug_assert!(end <= self.source.len());
+        TextRange::new(
+            TextSize::try_from(start).unwrap_or_else(|_| self.source.text_len()),
+            TextSize::try_from(end).unwrap_or_else(|_| self.source.text_len()),
+        )
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::{ConstructKind, Lexed, TokenKind, lex};
+
+    /// render the token stream as `kind:text` pairs, so a test reads as the
+    /// classification of the source rather than as a pile of offsets
+    fn classify(source: &str) -> Vec<String> {
+        lex(source)
+            .tokens()
+            .iter()
+            .map(|token| format!("{:?}:{}", token.kind, &source[token.range]))
+            .collect()
+    }
+
+    fn constructs(lexed: &Lexed, source: &str) -> Vec<String> {
+        lexed
+            .constructs()
+            .iter()
+            .map(|construct| {
+                format!(
+                    "{:?}({}):{}",
+                    construct.kind,
+                    construct.name(source),
+                    &source[construct.range]
+                )
+            })
+            .collect()
+    }
+
+    #[test]
+    fn plain_text_is_one_token() {
+        assert_eq!(classify("<p>hello</p>"), ["Text:<p>hello</p>"]);
+    }
+
+    #[test]
+    fn variable_with_attribute_and_filter() {
+        assert_eq!(
+            classify("{{ book.author.name|upper }}"),
+            [
+                "Delimiter:{{",
+                "Variable:book",
+                "Operator:.",
+                "Attribute:author",
+                "Operator:.",
+                "Attribute:name",
+                "Operator:|",
+                "FilterName:upper",
+                "Delimiter:}}",
+            ]
+        );
+    }
+
+    #[test]
+    fn filter_argument_is_a_string() {
+        assert_eq!(
+            classify(r#"{{ value|default:"none" }}"#),
+            [
+                "Delimiter:{{",
+                "Variable:value",
+                "Operator:|",
+                "FilterName:default",
+                "Operator::",
+                r#"String:"none""#,
+                "Delimiter:}}",
+            ]
+        );
+    }
+
+    #[test]
+    fn numeric_index_after_dot() {
+        assert_eq!(
+            classify("{{ row.0 }}"),
+            [
+                "Delimiter:{{",
+                "Variable:row",
+                "Operator:.",
+                "Attribute:0",
+                "Delimiter:}}",
+            ]
+        );
+    }
+
+    #[test]
+    fn tag_name_is_distinguished_from_its_arguments() {
+        assert_eq!(
+            classify("{% for book in books reversed %}"),
+            [
+                "Delimiter:{%",
+                "TagName:for",
+                "Variable:book",
+                "Keyword:in",
+                "Variable:books",
+                "Keyword:reversed",
+                "Delimiter:%}",
+            ]
+        );
+    }
+
+    #[test]
+    fn keyword_argument_is_reclassified_by_the_equals_that_follows() {
+        assert_eq!(
+            classify("{% include 'card.html' with title=book.title only %}"),
+            [
+                "Delimiter:{%",
+                "TagName:include",
+                "String:'card.html'",
+                "Keyword:with",
+                "KeywordArgument:title",
+                "Operator:=",
+                "Variable:book",
+                "Operator:.",
+                "Attribute:title",
+                "Keyword:only",
+                "Delimiter:%}",
+            ]
+        );
+    }
+
+    #[test]
+    fn comparison_operators_are_not_keyword_arguments() {
+        assert_eq!(
+            classify("{% if count >= 10 and other != 3 %}"),
+            [
+                "Delimiter:{%",
+                "TagName:if",
+                "Variable:count",
+                "Operator:>=",
+                "Number:10",
+                "Keyword:and",
+                "Variable:other",
+                "Operator:!=",
+                "Number:3",
+                "Delimiter:%}",
+            ]
+        );
+    }
+
+    #[test]
+    fn builtin_constants_are_their_own_kind() {
+        assert_eq!(
+            classify("{% if x is not None %}"),
+            [
+                "Delimiter:{%",
+                "TagName:if",
+                "Variable:x",
+                "Keyword:is",
+                "Keyword:not",
+                "BuiltinConstant:None",
+                "Delimiter:%}",
+            ]
+        );
+    }
+
+    #[test]
+    fn negative_and_float_numbers() {
+        assert_eq!(
+            classify("{{ x|floatformat:-2 }}{{ y|add:1.5 }}"),
+            [
+                "Delimiter:{{",
+                "Variable:x",
+                "Operator:|",
+                "FilterName:floatformat",
+                "Operator::",
+                "Number:-2",
+                "Delimiter:}}",
+                "Delimiter:{{",
+                "Variable:y",
+                "Operator:|",
+                "FilterName:add",
+                "Operator::",
+                "Number:1.5",
+                "Delimiter:}}",
+            ]
+        );
+    }
+
+    #[test]
+    fn dashed_names_lex_as_one_token() {
+        assert_eq!(
+            classify("{% partial comment-item %}"),
+            [
+                "Delimiter:{%",
+                "TagName:partial",
+                "Variable:comment-item",
+                "Delimiter:%}",
+            ]
+        );
+    }
+
+    #[test]
+    fn hash_comment() {
+        assert_eq!(
+            classify("{# todo: drop this #}"),
+            ["Delimiter:{#", "Comment: todo: drop this ", "Delimiter:#}"]
+        );
+    }
+
+    #[test]
+    fn comment_block_body_is_not_template_source() {
+        assert_eq!(
+            classify("{% comment %}{{ x }}{% endcomment %}"),
+            [
+                "Delimiter:{%",
+                "TagName:comment",
+                "Delimiter:%}",
+                "Comment:{{ x }}",
+                "Delimiter:{%",
+                "TagName:endcomment",
+                "Delimiter:%}",
+            ]
+        );
+    }
+
+    #[test]
+    fn verbatim_block_body_is_literal_text() {
+        assert_eq!(
+            classify("{% verbatim %}{{ x }}{% endverbatim %}"),
+            [
+                "Delimiter:{%",
+                "TagName:verbatim",
+                "Delimiter:%}",
+                "Text:{{ x }}",
+                "Delimiter:{%",
+                "TagName:endverbatim",
+                "Delimiter:%}",
+            ]
+        );
+    }
+
+    #[test]
+    fn unterminated_construct_stops_at_the_end_of_its_line() {
+        let source = "{% extends\n<p>text</p>";
+        assert_eq!(
+            classify(source),
+            ["Delimiter:{%", "TagName:extends", "Text:\n<p>text</p>",]
+        );
+
+        let lexed = lex(source);
+        assert_eq!(constructs(&lexed, source), ["Tag(extends):{% extends"]);
+        assert!(!lexed.constructs()[0].terminated);
+    }
+
+    #[test]
+    fn unterminated_raw_body_does_not_swallow_the_file() {
+        // the closing tag is missing, so the body must keep lexing as template
+        // source — otherwise everything the user types after `{% comment %}`
+        // would go dark until they type `{% endcomment %}`
+        assert_eq!(
+            classify("{% comment %}{{ x }}"),
+            [
+                "Delimiter:{%",
+                "TagName:comment",
+                "Delimiter:%}",
+                "Delimiter:{{",
+                "Variable:x",
+                "Delimiter:}}",
+            ]
+        );
+    }
+
+    #[test]
+    fn constructs_record_their_kind_and_name() {
+        let source = "a{{ x }}b{% if y %}c{# d #}";
+        let lexed = lex(source);
+        assert_eq!(
+            constructs(&lexed, source),
+            [
+                "Variable():{{ x }}",
+                "Tag(if):{% if y %}",
+                "Comment():{# d #}"
+            ]
+        );
+    }
+
+    #[test]
+    fn construct_at_finds_the_construct_around_an_offset() {
+        //                0        1
+        //                12345678901
+        let source = "a{{ x }}bb{% if y %}";
+        let lexed = lex(source);
+
+        let at = |offset: usize| {
+            lexed
+                .construct_at(ruff_text_size::TextSize::try_from(offset).unwrap())
+                .map(|construct| construct.name(source).to_string())
+        };
+
+        assert_eq!(at(0), None, "before any construct");
+        assert_eq!(at(1), Some(String::new()), "the `{{` itself");
+        assert_eq!(at(8), Some(String::new()), "the end of `}}`");
+        assert_eq!(at(9), None, "the literal text between them");
+        assert_eq!(at(14), Some("if".to_string()));
+        assert_eq!(at(20), Some("if".to_string()), "the closing delimiter");
+    }
+
+    #[test]
+    fn a_lone_brace_is_text() {
+        assert_eq!(classify("{ x }"), ["Text:{ x }"]);
+    }
+
+    #[test]
+    fn non_ascii_text_keeps_char_boundaries() {
+        // the lexer indexes by byte but must never split a code point
+        assert_eq!(
+            classify("héllo {{ wörld }}"),
+            [
+                "Text:héllo ",
+                "Delimiter:{{",
+                "Variable:wörld",
+                "Delimiter:}}",
+            ]
+        );
+    }
+
+    #[test]
+    fn tokens_are_ordered_and_never_overlap() {
+        let source = "a{{ x.y|f:'s' }}b{% if 1 %}{# c #}{% verbatim %}v{% endverbatim %}";
+        let lexed = lex(source);
+
+        let mut covered = 0usize;
+        for token in lexed.tokens() {
+            assert!(
+                usize::from(token.range.start()) >= covered,
+                "{token:?} overlaps the token before it"
+            );
+            assert!(token.range.end() > token.range.start(), "empty {token:?}");
+            covered = usize::from(token.range.end());
+        }
+        assert_eq!(covered, source.len(), "the tail of the source is uncovered");
+    }
+
+    #[test]
+    fn only_whitespace_inside_a_construct_is_left_uncovered() {
+        let source = "a{{ x }}b";
+        let lexed = lex(source);
+
+        let mut covered = 0usize;
+        for token in lexed.tokens() {
+            let gap = &source[covered..usize::from(token.range.start())];
+            assert!(gap.trim().is_empty(), "`{gap}` belongs to no token");
+            covered = usize::from(token.range.end());
+        }
+    }
+
+    #[test]
+    fn construct_kinds_round_trip() {
+        let lexed = lex("{{ a }}");
+        assert_eq!(lexed.constructs()[0].kind, ConstructKind::Variable);
+        assert!(lexed.constructs()[0].terminated);
+        assert!(
+            lexed
+                .construct_tokens(&lexed.constructs()[0])
+                .iter()
+                .any(|token| token.kind == TokenKind::Variable)
+        );
+    }
+}
diff --git a/crates/ty_ide/src/django_template/project.rs b/crates/ty_ide/src/django_template/project.rs
new file mode 100644
index 0000000000..217f6167f9
--- /dev/null
+++ b/crates/ty_ide/src/django_template/project.rs
@@ -0,0 +1,740 @@
+//! the django definitions a template needs from the project's python source
+//!
+//! everything a template can say that isn't a builtin comes from somewhere in
+//! the project: `{% load %}`ed tags and filters from its `templatetags` modules,
+//! `{% url %}` names from its url configuration, `{% extends %}` targets from its
+//! template directories, and the variables in `{{ }}` from whichever view renders
+//! the template. this module finds all of it.
+//!
+//! each source file is scanned by its own salsa query, and the project-wide
+//! answers are the union of those. that keeps an edit to one view from re-walking
+//! the whole project — and since the scans run off `parsed_module`, which the
+//! type checker has already populated for every project file, the ast work is
+//! shared rather than duplicated.
+
+use std::sync::Mutex;
+
+use compact_str::{CompactString, ToCompactString};
+use ruff_db::files::{File, FilePath, system_path_to_file};
+use ruff_db::parsed::parsed_module;
+use ruff_db::system::walk_directory::WalkState;
+use ruff_db::system::{FileType, SystemPath, SystemPathBuf};
+use ruff_python_ast::visitor::{Visitor, walk_expr, walk_stmt};
+use ruff_python_ast::{self as ast, Expr, Stmt};
+use ruff_text_size::{Ranged, TextRange};
+use ty_project::{Db, Project};
+
+/// the directory name django's app-directories template loader looks in
+const TEMPLATE_DIRECTORY: &str = "templates";
+
+/// the directory name django's `staticfiles` app-directories finder looks in
+const STATIC_DIRECTORY: &str = "static";
+
+/// the package name a project's template tag libraries live in
+const TEMPLATETAGS_PACKAGE: &str = "templatetags";
+
+/// how deep below the project root a `templates`/`static` directory is looked for
+///
+/// django's own layout puts them at `<project>/<app>/templates`, and a
+/// `<project>/src/<app>/templates` is about as deep as real projects go. bounding
+/// the walk keeps a large repository's `node_modules` or virtualenv from being
+/// crawled in full.
+const DISCOVERY_DEPTH: usize = 5;
+
+/// whether a tag or a filter was registered
+#[derive(Debug, Clone, Copy, PartialEq, Eq, get_size2::GetSize)]
+pub(crate) enum RegistrationKind {
+    /// `@register.simple_tag` and friends. `block` is set for the
+    /// `simple_block_tag` form, which takes a body and so needs an `{% end… %}`.
+    Tag { block: bool },
+    /// `@register.filter`
+    Filter,
+}
+
+/// a tag or filter one of the project's `templatetags` modules registers
+#[derive(Debug, Clone, PartialEq, Eq, get_size2::GetSize)]
+pub(crate) struct Registration {
+    pub(crate) name: CompactString,
+    pub(crate) kind: RegistrationKind,
+    /// the name a `{% load %}` uses, i.e. the module's own file stem
+    pub(crate) library: CompactString,
+    pub(crate) file: File,
+    /// the registered function's name, for navigation
+    pub(crate) range: TextRange,
+    pub(crate) documentation: Option<Box<str>>,
+}
+
+/// a name the project's url configuration gives a route
+#[derive(Debug, Clone, PartialEq, Eq, get_size2::GetSize)]
+pub(crate) struct UrlName {
+    /// the name a `{% url %}` reverses, namespace included
+    pub(crate) name: CompactString,
+    pub(crate) file: File,
+    /// the `name=` literal, for navigation
+    pub(crate) range: TextRange,
+    /// the route pattern, shown alongside the completion
+    pub(crate) route: Option<Box<str>>,
+}
+
+/// a name a view puts in a template's context
+#[derive(Debug, Clone, PartialEq, Eq, get_size2::GetSize)]
+pub(crate) struct ContextVariable {
+    pub(crate) name: CompactString,
+    pub(crate) file: File,
+    /// the key or attribute that declares the name, for navigation
+    pub(crate) range: TextRange,
+    /// the expression the view binds to the name
+    ///
+    /// this is what the completions infer the variable's type from, which is how
+    /// a django model in the context brings its fields with it.
+    pub(crate) value: Option<TextRange>,
+}
+
+/// the context one template is rendered with, from one place that renders it
+#[derive(Debug, Clone, PartialEq, Eq, get_size2::GetSize)]
+pub(crate) struct TemplateContext {
+    /// the template the view names, as the loader sees it
+    pub(crate) template: CompactString,
+    pub(crate) variables: Box<[ContextVariable]>,
+}
+
+/// a file inside one of the project's template directories
+#[derive(Debug, Clone, PartialEq, Eq, get_size2::GetSize)]
+pub(crate) struct DiscoveredFile {
+    /// the path relative to the directory it was found under, which is the name
+    /// `{% extends %}`, `{% include %}` and `{% static %}` all use
+    pub(crate) name: CompactString,
+    pub(crate) path: SystemPathBuf,
+}
+
+/// every file under a `templates` directory of the project
+#[salsa::tracked(returns(ref), heap_size=ruff_memory_usage::heap_size)]
+pub(crate) fn template_files(db: &dyn Db, project: Project) -> Box<[DiscoveredFile]> {
+    discover(db, project, TEMPLATE_DIRECTORY)
+}
+
+/// every file under a `static` directory of the project
+#[salsa::tracked(returns(ref), heap_size=ruff_memory_usage::heap_size)]
+pub(crate) fn static_files(db: &dyn Db, project: Project) -> Box<[DiscoveredFile]> {
+    discover(db, project, STATIC_DIRECTORY)
+}
+
+/// the file a template name resolves to
+pub(crate) fn resolve_template(db: &dyn Db, name: &str) -> Option<File> {
+    let path = template_files(db, db.project())
+        .iter()
+        .find(|candidate| candidate.name == name)
+        .map(|candidate| candidate.path.clone())?;
+
+    system_path_to_file(db, &path).ok()
+}
+
+/// every tag and filter the project registers
+#[salsa::tracked(returns(ref), heap_size=ruff_memory_usage::heap_size)]
+pub(crate) fn registrations(db: &dyn Db, project: Project) -> Box<[Registration]> {
+    project_scan(db, project, |db, file| {
+        // only a module inside a `templatetags` package is a tag library, so
+        // there is no point parsing anything else
+        is_templatetags_module(db, file)
+            .then(|| registrations_in_file(db, file).iter().cloned())
+            .into_iter()
+            .flatten()
+    })
+}
+
+/// every name the project's url configuration defines
+#[salsa::tracked(returns(ref), heap_size=ruff_memory_usage::heap_size)]
+pub(crate) fn url_names(db: &dyn Db, project: Project) -> Box<[UrlName]> {
+    project_scan(db, project, |db, file| {
+        url_names_in_file(db, file).iter().cloned()
+    })
+}
+
+/// every template context the project's views build
+#[salsa::tracked(returns(ref), heap_size=ruff_memory_usage::heap_size)]
+pub(crate) fn template_contexts(db: &dyn Db, project: Project) -> Box<[TemplateContext]> {
+    project_scan(db, project, |db, file| {
+        template_contexts_in_file(db, file).iter().cloned()
+    })
+}
+
+/// the names every view that renders `template` puts in its context
+///
+/// two views rendering the same template contribute both their contexts, since
+/// either may be the one running. a name several views agree on appears once.
+pub(crate) fn context_for_template<'db>(
+    db: &'db dyn Db,
+    template: &str,
+) -> Vec<&'db ContextVariable> {
+    let mut seen: Vec<&ContextVariable> = Vec::new();
+
+    for context in template_contexts(db, db.project())
+        .iter()
+        .filter(|context| context.template == template)
+    {
+        for variable in &context.variables {
+            if !seen.iter().any(|existing| existing.name == variable.name) {
+                seen.push(variable);
+            }
+        }
+    }
+
+    seen
+}
+
+/// run `scan` over every first-party source file of the project
+fn project_scan<'db, T, I>(
+    db: &'db dyn Db,
+    project: Project,
+    scan: impl Fn(&'db dyn Db, File) -> I,
+) -> Box<[T]>
+where
+    I: IntoIterator<Item = T>,
+{
+    let mut found = Vec::new();
+
+    for file in &project.files(db) {
+        // a stub declares types, never a url pattern or a rendered template
+        if file.path(db).extension() == Some("pyi") {
+            continue;
+        }
+        found.extend(scan(db, file));
+    }
+
+    found.into_boxed_slice()
+}
+
+/// find every file under a directory named `directory`, anywhere in the project
+///
+/// the walk is bounded (see [`DISCOVERY_DEPTH`]) and respects the project's
+/// ignore-file settings, so a repository's dependencies are not crawled.
+fn discover(db: &dyn Db, project: Project, directory: &str) -> Box<[DiscoveredFile]> {
+    let root = project.root(db);
+    let found = Mutex::new(Vec::new());
+
+    db.system()
+        .walk_directory(root)
+        .standard_filters(project.settings(db).src().respect_ignore_files)
+        .ignore_hidden(true)
+        .run(|| {
+            Box::new(|entry| {
+                let Ok(entry) = entry else {
+                    return WalkState::Continue;
+                };
+
+                let inside = entry
+                    .path()
+                    .ancestors()
+                    .any(|ancestor| ancestor.file_name() == Some(directory));
+
+                match entry.file_type() {
+                    FileType::Directory => {
+                        // stop descending once the entry is neither a candidate
+                        // root nor already inside one
+                        if !inside && entry.depth() >= DISCOVERY_DEPTH {
+                            return WalkState::Skip;
+                        }
+                        WalkState::Continue
+                    }
+                    FileType::File => {
+                        if inside && let Some(name) = relative_to_directory(entry.path(), directory)
+                        {
+                            found.lock().unwrap().push(DiscoveredFile {
+                                name,
+                                path: entry.path().to_path_buf(),
+                            });
+                        }
+                        WalkState::Continue
+                    }
+                    FileType::Symlink => WalkState::Continue,
+                }
+            })
+        });
+
+    let mut found = found
+        .into_inner()
+        .unwrap_or_else(std::sync::PoisonError::into_inner);
+    found.sort_by(|left, right| left.name.cmp(&right.name).then(left.path.cmp(&right.path)));
+    found.dedup_by(|left, right| left.name == right.name && left.path == right.path);
+    found.into_boxed_slice()
+}
+
+/// the part of `path` below its innermost `directory` ancestor
+///
+/// `/app/templates/blog/post.html` under `templates` is `blog/post.html`, which
+/// is exactly the name a `{% include %}` writes.
+fn relative_to_directory(path: &SystemPath, directory: &str) -> Option<CompactString> {
+    let root = path
+        .ancestors()
+        .find(|ancestor| ancestor.file_name() == Some(directory))?;
+
+    Some(
+        path.strip_prefix(root)
+            .ok()?
+            .as_str()
+            .replace('\\', "/")
+            .to_compact_string(),
+    )
+}
+
+/// whether `file` is a module of a `templatetags` package
+fn is_templatetags_module(db: &dyn Db, file: File) -> bool {
+    let FilePath::System(path) = file.path(db) else {
+        return false;
+    };
+
+    path.parent()
+        .is_some_and(|parent| parent.file_name() == Some(TEMPLATETAGS_PACKAGE))
+        && path.file_stem() != Some("__init__")
+}
+
+/// the tags and filters one `templatetags` module registers
+#[salsa::tracked(returns(ref), heap_size=ruff_memory_usage::heap_size)]
+fn registrations_in_file(db: &dyn Db, file: File) -> Box<[Registration]> {
+    let Some(library) = file
+        .path(db)
+        .as_system_path()
+        .and_then(SystemPath::file_stem)
+    else {
+        return Box::default();
+    };
+    let library = library.to_compact_string();
+
+    let parsed = parsed_module(db, file).load(db);
+    let mut visitor = RegistrationVisitor {
+        file,
+        library,
+        registers: library_names(parsed.suite()),
+        found: Vec::new(),
+    };
+    visitor.visit_body(parsed.suite());
+
+    visitor.found.into_boxed_slice()
+}
+
+/// the names the module binds a `template.Library()` to
+///
+/// django's own documentation always calls it `register`, and code that doesn't
+/// is rare enough that the conventional name is the right fallback when no
+/// `Library()` call is found at all.
+fn library_names(body: &[Stmt]) -> Vec<CompactString> {
+    let mut names: Vec<CompactString> = body
+        .iter()
+        .filter_map(|statement| {
+            let Stmt::Assign(assign) = statement else {
+                return None;
+            };
+            let Expr::Call(call) = &*assign.value else {
+                return None;
+            };
+            (callee_name(&call.func)? == "Library").then_some(&assign.targets)
+        })
+        .flatten()
+        .filter_map(|target| match target {
+            Expr::Name(name) => Some(name.id.to_compact_string()),
+            _ => None,
+        })
+        .collect();
+
+    if names.is_empty() {
+        names.push("register".to_compact_string());
+    }
+    names
+}
+
+struct RegistrationVisitor {
+    file: File,
+    library: CompactString,
+    registers: Vec<CompactString>,
+    found: Vec<Registration>,
+}
+
+impl RegistrationVisitor {
+    /// the registration `decorator` makes of the function named `function`
+    fn registration(
+        &self,
+        decorator: &ast::Decorator,
+        function: &ast::Identifier,
+        documentation: Option<Box<str>>,
+    ) -> Option<Registration> {
+        // `@register.filter` and `@register.filter(name="x")` both apply
+        let (attribute, call) = match &decorator.expression {
+            Expr::Attribute(attribute) => (attribute, None),
+            Expr::Call(call) => match &*call.func {
+                Expr::Attribute(attribute) => (attribute, Some(call)),
+                _ => return None,
+            },
+            _ => return None,
+        };
+
+        let Expr::Name(object) = &*attribute.value else {
+            return None;
+        };
+        if !self.registers.iter().any(|name| name == object.id.as_str()) {
+            return None;
+        }
+
+        let kind = match attribute.attr.as_str() {
+            "filter" | "filter_function" => RegistrationKind::Filter,
+            "simple_block_tag" => RegistrationKind::Tag { block: true },
+            "tag" | "simple_tag" | "inclusion_tag" => RegistrationKind::Tag { block: false },
+            _ => return None,
+        };
+
+        Some(Registration {
+            name: registered_name(attribute.attr.as_str(), call, function),
+            kind,
+            library: self.library.clone(),
+            file: self.file,
+            range: function.range(),
+            documentation,
+        })
+    }
+}
+
+impl<'ast> Visitor<'ast> for RegistrationVisitor {
+    fn visit_stmt(&mut self, stmt: &'ast Stmt) {
+        if let Stmt::FunctionDef(function) = stmt {
+            let documentation = docstring_summary(&function.body);
+            // one function is one tag even if it somehow carries two registering
+            // decorators; the first is the one that names it
+            let registration = function.decorator_list.iter().find_map(|decorator| {
+                self.registration(decorator, &function.name, documentation.clone())
+            });
+            self.found.extend(registration);
+            return;
+        }
+
+        walk_stmt(self, stmt);
+    }
+}
+
+/// the name a registration goes by
+///
+/// `@register.inclusion_tag("card.html")` names a *template* with its first
+/// argument, not the tag, which is the one case where the positional argument
+/// must not be read as a name.
+fn registered_name(
+    attribute: &str,
+    call: Option<&ast::ExprCall>,
+    function: &ast::Identifier,
+) -> CompactString {
+    let Some(call) = call else {
+        return function.id.to_compact_string();
+    };
+
+    if let Some(name) = call
+        .arguments
+        .find_keyword("name")
+        .and_then(|keyword| string_literal(&keyword.value))
+    {
+        return name;
+    }
+
+    if attribute != "inclusion_tag"
+        && let Some(name) = call.arguments.args.first().and_then(string_literal)
+    {
+        return name;
+    }
+
+    function.id.to_compact_string()
+}
+
+/// the url names one module defines
+#[salsa::tracked(returns(ref), heap_size=ruff_memory_usage::heap_size)]
+fn url_names_in_file(db: &dyn Db, file: File) -> Box<[UrlName]> {
+    let parsed = parsed_module(db, file).load(db);
+
+    // django namespaces an included module's names under its `app_name`
+    let namespace = parsed.suite().iter().find_map(|statement| {
+        let Stmt::Assign(assign) = statement else {
+            return None;
+        };
+        let [Expr::Name(target)] = assign.targets.as_slice() else {
+            return None;
+        };
+        (target.id == "app_name").then(|| string_literal(&assign.value))?
+    });
+
+    let mut visitor = UrlVisitor {
+        file,
+        namespace,
+        found: Vec::new(),
+    };
+    visitor.visit_body(parsed.suite());
+
+    visitor.found.into_boxed_slice()
+}
+
+struct UrlVisitor {
+    file: File,
+    namespace: Option<CompactString>,
+    found: Vec<UrlName>,
+}
+
+impl<'ast> Visitor<'ast> for UrlVisitor {
+    fn visit_expr(&mut self, expr: &'ast Expr) {
+        if let Expr::Call(call) = expr
+            && matches!(
+                callee_name(&call.func).as_deref(),
+                Some("path" | "re_path" | "url")
+            )
+            && let Some(keyword) = call.arguments.find_keyword("name")
+            && let Some(name) = string_literal(&keyword.value)
+        {
+            let name = match &self.namespace {
+                Some(namespace) => format!("{namespace}:{name}").to_compact_string(),
+                None => name,
+            };
+
+            self.found.push(UrlName {
+                name,
+                file: self.file,
+                range: keyword.value.range(),
+                route: call
+                    .arguments
+                    .args
+                    .first()
+                    .and_then(string_literal)
+                    .map(|route| Box::from(route.as_str())),
+            });
+        }
+
+        walk_expr(self, expr);
+    }
+}
+
+/// the template contexts one module builds
+#[salsa::tracked(returns(ref), heap_size=ruff_memory_usage::heap_size)]
+fn template_contexts_in_file(db: &dyn Db, file: File) -> Box<[TemplateContext]> {
+    let parsed = parsed_module(db, file).load(db);
+
+    let mut visitor = ContextVisitor {
+        file,
+        found: Vec::new(),
+    };
+    visitor.visit_body(parsed.suite());
+
+    visitor.found.into_boxed_slice()
+}
+
+struct ContextVisitor {
+    file: File,
+    found: Vec<TemplateContext>,
+}
+
+impl ContextVisitor {
+    /// the context a `render()`/`TemplateResponse()` call passes
+    ///
+    /// both take the request first, the template second and the context third,
+    /// and both accept those last two by keyword as well.
+    fn render_call(&self, call: &ast::ExprCall) -> Option<TemplateContext> {
+        let callee = callee_name(&call.func)?;
+        let (template_index, context_index) = match callee.as_str() {
+            "render" | "TemplateResponse" => (1, 2),
+            _ => return None,
+        };
+
+        let template = call
+            .arguments
+            .find_keyword("template_name")
+            .map(|keyword| &keyword.value)
+            .or_else(|| call.arguments.args.get(template_index))
+            .and_then(string_literal)?;
+
+        let context = call
+            .arguments
+            .find_keyword("context")
+            .map(|keyword| &keyword.value)
+            .or_else(|| call.arguments.args.get(context_index));
+
+        Some(TemplateContext {
+            template,
+            variables: context
+                .map(|context| self.dict_variables(context))
+                .unwrap_or_default(),
+        })
+    }
+
+    /// the names a dict literal binds
+    fn dict_variables(&self, expr: &Expr) -> Box<[ContextVariable]> {
+        let Expr::Dict(dict) = expr else {
+            return Box::default();
+        };
+
+        dict.items
+            .iter()
+            .filter_map(|item| {
+                let key = item.key.as_ref()?;
+                Some(ContextVariable {
+                    name: string_literal(key)?,
+                    file: self.file,
+                    range: key.range(),
+                    value: Some(item.value.range()),
+                })
+            })
+            .collect()
+    }
+
+    /// the context a class-based view declares
+    ///
+    /// django's generic views name their template with `template_name` and their
+    /// object with `context_object_name`, and add anything else through
+    /// `extra_context` or by writing into the dict `get_context_data` returns.
+    fn class_based_view(&self, class: &ast::StmtClassDef) -> Option<TemplateContext> {
+        let template = class
+            .body
+            .iter()
+            .find_map(|statement| class_attribute(statement, "template_name"))
+            .and_then(|(value, _)| string_literal(value))?;
+
+        let mut variables = Vec::new();
+
+        for statement in &class.body {
+            if let Some((value, range)) = class_attribute(statement, "context_object_name")
+                && let Some(name) = string_literal(value)
+            {
+                variables.push(ContextVariable {
+                    name,
+                    file: self.file,
+                    range,
+                    // the object itself is what the view will bind; its type
+                    // comes from the view's generics, which is beyond what a
+                    // syntactic scan can follow
+                    value: None,
+                });
+            }
+
+            if let Some((value, _)) = class_attribute(statement, "extra_context") {
+                variables.extend(self.dict_variables(value));
+            }
+
+            if let Stmt::FunctionDef(function) = statement
+                && function.name.as_str() == "get_context_data"
+            {
+                variables.extend(self.context_assignments(&function.body));
+            }
+        }
+
+        Some(TemplateContext {
+            template,
+            variables: variables.into_boxed_slice(),
+        })
+    }
+
+    /// the names a `get_context_data` body writes into its context dict
+    fn context_assignments(&self, body: &[Stmt]) -> Vec<ContextVariable> {
+        let mut found = Vec::new();
+
+        let mut visitor = ContextAssignmentVisitor {
+            file: self.file,
+            found: &mut found,
+        };
+        visitor.visit_body(body);
+
+        found
+    }
+}
+
+impl<'ast> Visitor<'ast> for ContextVisitor {
+    fn visit_stmt(&mut self, stmt: &'ast Stmt) {
+        if let Stmt::ClassDef(class) = stmt {
+            self.found.extend(self.class_based_view(class));
+            return;
+        }
+
+        walk_stmt(self, stmt);
+    }
+
+    fn visit_expr(&mut self, expr: &'ast Expr) {
+        if let Expr::Call(call) = expr {
+            self.found.extend(self.render_call(call));
+        }
+
+        walk_expr(self, expr);
+    }
+}
+
+/// collects `context["name"] = value` writes
+struct ContextAssignmentVisitor<'a> {
+    file: File,
+    found: &'a mut Vec<ContextVariable>,
+}
+
+impl<'ast> Visitor<'ast> for ContextAssignmentVisitor<'_> {
+    fn visit_stmt(&mut self, stmt: &'ast Stmt) {
+        if let Stmt::Assign(assign) = stmt
+            && let [Expr::Subscript(subscript)] = assign.targets.as_slice()
+            && let Some(name) = string_literal(&subscript.slice)
+        {
+            self.found.push(ContextVariable {
+                name,
+                file: self.file,
+                range: subscript.slice.range(),
+                value: Some(assign.value.range()),
+            });
+        }
+
+        walk_stmt(self, stmt);
+    }
+}
+
+/// the value and name range of a class-body assignment to `attribute`
+fn class_attribute<'ast>(
+    statement: &'ast Stmt,
+    attribute: &str,
+) -> Option<(&'ast Expr, TextRange)> {
+    match statement {
+        Stmt::Assign(assign) => {
+            let [Expr::Name(target)] = assign.targets.as_slice() else {
+                return None;
+            };
+            (target.id == attribute).then(|| (&*assign.value, target.range()))
+        }
+        Stmt::AnnAssign(assign) => {
+            let Expr::Name(target) = &*assign.target else {
+                return None;
+            };
+            let value = assign.value.as_deref()?;
+            (target.id == attribute).then(|| (value, target.range()))
+        }
+        _ => None,
+    }
+}
+
+/// the final segment of a callee, so that `render` and `shortcuts.render` are one
+fn callee_name(func: &Expr) -> Option<CompactString> {
+    match func {
+        Expr::Name(name) => Some(name.id.to_compact_string()),
+        Expr::Attribute(attribute) => Some(attribute.attr.id.to_compact_string()),
+        _ => None,
+    }
+}
+
+/// the value of a plain string literal
+fn string_literal(expr: &Expr) -> Option<CompactString> {
+    match expr {
+        Expr::StringLiteral(literal) => Some(literal.value.to_str().to_compact_string()),
+        _ => None,
+    }
+}
+
+/// the first paragraph of a body's docstring
+fn docstring_summary(body: &[Stmt]) -> Option<Box<str>> {
+    let Stmt::Expr(first) = body.first()? else {
+        return None;
+    };
+    let Expr::StringLiteral(literal) = &*first.value else {
+        return None;
+    };
+
+    let text = literal.value.to_str();
+    let summary: String = text
+        .lines()
+        .map(str::trim)
+        .take_while(|line| !line.is_empty())
+        .collect::<Vec<_>>()
+        .join(" ");
+
+    (!summary.is_empty()).then(|| Box::from(summary.as_str()))
+}
diff --git a/crates/ty_ide/src/django_template/resolve.rs b/crates/ty_ide/src/django_template/resolve.rs
new file mode 100644
index 0000000000..cf08b6db90
--- /dev/null
+++ b/crates/ty_ide/src/django_template/resolve.rs
@@ -0,0 +1,222 @@
+//! joining a template's variable paths to the python types behind them
+//!
+//! this is what makes template support more than a syntax mode. `{{ book.a… }}`
+//! can only be completed if `book` is known to be a `Book`, and `book` is only
+//! known to be a `Book` because some view wrote `render(request, "…", {"book":
+//! book})` and the type checker knows what that `book` is. the chain runs
+//! template binding → context entry → python expression → [`Type`], and each link
+//! is one function here.
+
+use ruff_db::files::{File, FilePath};
+use ruff_db::parsed::parsed_module;
+use ruff_python_ast::find_node::covering_node;
+use ruff_text_size::{Ranged, TextRange, TextSize};
+use ty_project::Db;
+use ty_python_semantic::types::Type;
+use ty_python_semantic::types::ide_support::iterable_element_type;
+use ty_python_semantic::types::list_members::{Member, all_members};
+use ty_python_semantic::{HasType, SemanticModel};
+
+use super::index::{Binding, BindingOrigin, TemplateIndex};
+use super::lexer::TokenKind;
+use super::project::{self, ContextVariable};
+
+/// how many `{% with %}` hops a path is followed through before giving up
+///
+/// a template can write `{% with a=b %}{% with b=a %}`, which has no fixed point;
+/// the limit is what keeps resolution total rather than the shape of the input.
+const MAX_INDIRECTIONS: u32 = 8;
+
+/// what a name written in a template refers to
+#[derive(Debug, Clone, Copy)]
+pub(crate) enum Origin<'a> {
+    /// a tag in this template bound it
+    Binding(&'a Binding),
+    /// a view put it in this template's context
+    Context(&'a ContextVariable),
+}
+
+/// what the name `name`, written at `offset`, refers to
+///
+/// a name a tag binds shadows one from the context, exactly as it does at render
+/// time.
+pub(crate) fn resolve_root<'a>(
+    db: &'a dyn Db,
+    template: File,
+    index: &'a TemplateIndex,
+    offset: TextSize,
+    name: &str,
+) -> Option<Origin<'a>> {
+    if let Some(binding) = index.resolve_binding(name, offset) {
+        return Some(Origin::Binding(binding));
+    }
+
+    context_variables(db, template)
+        .into_iter()
+        .find(|variable| variable.name == name)
+        .map(Origin::Context)
+}
+
+/// every name the project's views put in this template's context
+pub(crate) fn context_variables(db: &dyn Db, template: File) -> Vec<&ContextVariable> {
+    let Some(name) = template_name(db, template) else {
+        return Vec::new();
+    };
+
+    project::context_for_template(db, &name)
+}
+
+/// the name the template loader knows `file` by, e.g. `blog/post.html`
+pub(crate) fn template_name(db: &dyn Db, file: File) -> Option<String> {
+    let FilePath::System(path) = file.path(db) else {
+        return None;
+    };
+
+    project::template_files(db, db.project())
+        .iter()
+        .find(|candidate| *candidate.path == **path)
+        .map(|candidate| candidate.name.to_string())
+}
+
+/// the type of the dotted path `segments`, written at `offset` of `template`
+///
+/// `segments` is the path as written: `["book", "author", "name"]` for
+/// `book.author.name`. the empty path has no type.
+pub(crate) fn path_type<'db>(
+    db: &'db dyn Db,
+    template: File,
+    index: &TemplateIndex,
+    source: &str,
+    offset: TextSize,
+    segments: &[&str],
+) -> Option<Type<'db>> {
+    resolve_path(
+        db,
+        template,
+        index,
+        source,
+        offset,
+        segments,
+        MAX_INDIRECTIONS,
+    )
+}
+
+fn resolve_path<'db>(
+    db: &'db dyn Db,
+    template: File,
+    index: &TemplateIndex,
+    source: &str,
+    offset: TextSize,
+    segments: &[&str],
+    fuel: u32,
+) -> Option<Type<'db>> {
+    let (root, rest) = segments.split_first()?;
+    let mut ty = root_type(db, template, index, source, offset, root, fuel)?;
+
+    for segment in rest {
+        ty = member_type(db, ty, segment)?;
+    }
+
+    Some(ty)
+}
+
+/// the type of the leading name of a path
+fn root_type<'db>(
+    db: &'db dyn Db,
+    template: File,
+    index: &TemplateIndex,
+    source: &str,
+    offset: TextSize,
+    name: &str,
+    fuel: u32,
+) -> Option<Type<'db>> {
+    if fuel == 0 {
+        return None;
+    }
+
+    match resolve_root(db, template, index, offset, name)? {
+        Origin::Binding(binding) => {
+            // django's `forloop` is built by the template engine, not by any
+            // python type the project could name
+            if binding.origin == BindingOrigin::ForLoop {
+                return None;
+            }
+
+            let value = binding.value?;
+            let segments = path_segments(index, source, value);
+            let value_type = resolve_path(
+                db,
+                template,
+                index,
+                source,
+                // the tag's value expression is written in the tag itself, so it
+                // resolves in the scope *before* this binding takes effect
+                binding.range.start(),
+                &segments,
+                fuel - 1,
+            )?;
+
+            match binding.origin {
+                BindingOrigin::LoopVariable => iterable_element_type(db, value_type),
+                BindingOrigin::Alias | BindingOrigin::ForLoop => Some(value_type),
+            }
+        }
+        Origin::Context(variable) => expression_type(db, variable.file, variable.value?),
+    }
+}
+
+/// the names making up the dotted path covering `range` of the template
+pub(crate) fn path_segments<'src>(
+    index: &TemplateIndex,
+    source: &'src str,
+    range: TextRange,
+) -> Vec<&'src str> {
+    index
+        .lexed()
+        .tokens()
+        .iter()
+        .filter(|token| range.contains_range(token.range))
+        .filter(|token| matches!(token.kind, TokenKind::Variable | TokenKind::Attribute))
+        .map(|token| &source[token.range])
+        .collect()
+}
+
+/// the type of `name` accessed on `ty`
+///
+/// django's variable lookup tries a dictionary subscript before an attribute, but
+/// a mapping's keys are values rather than types, so an attribute is all a static
+/// answer can cover.
+pub(crate) fn member_type<'db>(db: &'db dyn Db, ty: Type<'db>, name: &str) -> Option<Type<'db>> {
+    members(db, ty)
+        .into_iter()
+        .find(|member| member.name == name)
+        .map(|member| member.ty)
+}
+
+/// every attribute a value of type `ty` has, in name order
+pub(crate) fn members<'db>(db: &'db dyn Db, ty: Type<'db>) -> Vec<Member<'db>> {
+    let mut members: Vec<_> = all_members(db, ty)
+        .into_iter()
+        // a template can only write a `\w+` name after a dot, so a dunder is both
+        // unreachable and noise
+        .filter(|member| !member.name.starts_with('_'))
+        .collect();
+
+    members.sort_unstable_by(|left, right| left.name.cmp(&right.name));
+    members
+}
+
+/// the type of the python expression at `range` of `file`
+pub(crate) fn expression_type(db: &dyn Db, file: File, range: TextRange) -> Option<Type<'_>> {
+    let parsed = parsed_module(db, file).load(db);
+    let covering = covering_node(parsed.syntax().into(), range);
+
+    // the smallest node covering the range must be the expression itself; a
+    // larger one means the range no longer picks out an expression
+    if covering.node().range() != range {
+        return None;
+    }
+
+    let expression = covering.node().as_expr_ref()?;
+    expression.inferred_type(&SemanticModel::new(db, file))
+}
diff --git a/crates/ty_ide/src/django_template/semantic_tokens.rs b/crates/ty_ide/src/django_template/semantic_tokens.rs
new file mode 100644
index 0000000000..6c1473e1b4
--- /dev/null
+++ b/crates/ty_ide/src/django_template/semantic_tokens.rs
@@ -0,0 +1,357 @@
+//! semantic highlighting for django templates
+//!
+//! the editor already has a grammar for whatever markup surrounds the template
+//! constructs, so this deliberately emits nothing for literal text and confines
+//! itself to what a textmate grammar cannot know: whether a tag or filter is
+//! django's own or the project's, whether a name is a variable or an attribute
+//! of one, and which names the template itself binds.
+
+use ruff_text_size::TextRange;
+
+use crate::semantic_tokens::{SemanticToken, SemanticTokenModifier, SemanticTokenType};
+
+use super::builtins;
+use super::index::{BindingOrigin, TemplateIndex};
+use super::lexer::TokenKind;
+
+/// the semantic tokens of a template, restricted to `range` when one is given
+pub(crate) fn semantic_tokens(
+    index: &TemplateIndex,
+    source: &str,
+    range: Option<TextRange>,
+) -> Vec<SemanticToken> {
+    // the names a tag introduces get the `definition` modifier, and a
+    // `{% block %}`/`{% partialdef %}` name is highlighted as the fragment it
+    // names rather than as a variable that happens to sit inside a tag
+    let mut definitions: Vec<(TextRange, SemanticTokenType)> = index
+        .blocks()
+        .iter()
+        .chain(index.partials())
+        .map(|definition| (definition.name_range, SemanticTokenType::Function))
+        .chain(
+            index
+                .bindings()
+                .iter()
+                // `forloop` is bound by the `{% for %}` tag itself rather than
+                // written anywhere, and its range is the tag's own name — which
+                // must keep being highlighted as the tag it is
+                .filter(|binding| binding.origin != BindingOrigin::ForLoop)
+                .map(|binding| (binding.range, SemanticTokenType::Variable)),
+        )
+        .collect();
+    definitions.sort_unstable_by_key(|(range, _)| range.start());
+
+    index
+        .lexed()
+        .tokens()
+        .iter()
+        // a token that merely abuts the requested range does not overlap it
+        .filter(|token| {
+            range.is_none_or(|range| {
+                range
+                    .intersect(token.range)
+                    .is_some_and(|overlap| !overlap.is_empty())
+            })
+        })
+        .filter_map(|token| {
+            let text = &source[token.range];
+            let (mut token_type, mut modifiers) = classify(token.kind, text)?;
+
+            if let Ok(found) =
+                definitions.binary_search_by_key(&token.range.start(), |(range, _)| range.start())
+                && definitions[found].0 == token.range
+            {
+                token_type = definitions[found].1;
+                modifiers |= SemanticTokenModifier::DEFINITION;
+            }
+
+            Some(SemanticToken {
+                range: token.range,
+                token_type,
+                modifiers,
+            })
+        })
+        .collect()
+}
+
+/// the token type and modifiers a lexed token carries, or `None` when it should
+/// be left to the editor's own grammar
+fn classify(kind: TokenKind, text: &str) -> Option<(SemanticTokenType, SemanticTokenModifier)> {
+    let empty = SemanticTokenModifier::empty();
+
+    Some(match kind {
+        // the markup around a construct is the editor's business, not ours
+        TokenKind::Text | TokenKind::Unknown => return None,
+        TokenKind::Delimiter | TokenKind::Operator => (SemanticTokenType::Operator, empty),
+        TokenKind::Comment => (SemanticTokenType::Comment, empty),
+        TokenKind::TagName => (
+            SemanticTokenType::Keyword,
+            default_library(is_builtin_tag(text)),
+        ),
+        TokenKind::FilterName => (
+            SemanticTokenType::Function,
+            default_library(builtins::filter(text).is_some()),
+        ),
+        TokenKind::Variable => (SemanticTokenType::Variable, empty),
+        TokenKind::Attribute => (SemanticTokenType::Property, empty),
+        TokenKind::KeywordArgument => (SemanticTokenType::Parameter, empty),
+        TokenKind::Keyword => (SemanticTokenType::Keyword, empty),
+        TokenKind::BuiltinConstant => (SemanticTokenType::BuiltinConstant, empty),
+        TokenKind::String => (SemanticTokenType::String, empty),
+        TokenKind::Number => (SemanticTokenType::Number, empty),
+    })
+}
+
+/// whether `name` is one of django's own tags, closing and branch tags included
+///
+/// the builtin table lists a closing tag only as the `closed_by` of the tag it
+/// closes, and a branch tag only as one of its `branches`, but `{% endfor %}` and
+/// `{% empty %}` are as much django's as `{% for %}` is.
+fn is_builtin_tag(name: &str) -> bool {
+    builtins::tag(name).is_some()
+        || builtins::TAGS
+            .iter()
+            .any(|tag| tag.closed_by == Some(name) || tag.branches.contains(&name))
+}
+
+fn default_library(is_builtin: bool) -> SemanticTokenModifier {
+    if is_builtin {
+        SemanticTokenModifier::DEFAULT_LIBRARY
+    } else {
+        SemanticTokenModifier::empty()
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use ruff_text_size::TextRange;
+
+    use crate::semantic_tokens::SemanticTokenModifier;
+
+    use super::super::index::TemplateIndex;
+    use super::semantic_tokens;
+
+    /// render the tokens as `type[+modifier…]:text`
+    fn highlight(source: &str) -> Vec<String> {
+        let index = TemplateIndex::from_source(source);
+        semantic_tokens(&index, source, None)
+            .into_iter()
+            .map(|token| {
+                let names: Vec<_> = SemanticTokenModifier::all_names()
+                    .into_iter()
+                    .enumerate()
+                    .filter(|(bit, _)| token.modifiers.bits() & (1 << bit) != 0)
+                    .map(|(_, name)| name)
+                    .collect();
+                let modifiers = if names.is_empty() {
+                    String::new()
+                } else {
+                    format!("+{}", names.join("+"))
+                };
+
+                format!(
+                    "{}{modifiers}:{}",
+                    token.token_type.as_lsp_concept(),
+                    &source[token.range]
+                )
+            })
+            .collect()
+    }
+
+    #[test]
+    fn literal_markup_is_left_to_the_editors_own_grammar() {
+        assert!(highlight("<p class=\"x\">hello</p>").is_empty());
+    }
+
+    #[test]
+    fn a_variable_expression() {
+        assert_eq!(
+            highlight("{{ book.title|upper }}"),
+            [
+                "operator:{{",
+                "variable:book",
+                "operator:.",
+                "property:title",
+                "operator:|",
+                "function+defaultLibrary:upper",
+                "operator:}}",
+            ]
+        );
+    }
+
+    #[test]
+    fn a_projects_own_filter_is_not_marked_as_djangos() {
+        assert_eq!(
+            highlight("{{ x|intcomma }}"),
+            [
+                "operator:{{",
+                "variable:x",
+                "operator:|",
+                "function:intcomma",
+                "operator:}}",
+            ]
+        );
+    }
+
+    #[test]
+    fn builtin_tags_and_their_closing_tags_are_both_djangos() {
+        assert_eq!(
+            highlight("{% spaceless %}{% endspaceless %}"),
+            [
+                "operator:{%",
+                "keyword+defaultLibrary:spaceless",
+                "operator:%}",
+                "operator:{%",
+                "keyword+defaultLibrary:endspaceless",
+                "operator:%}",
+            ]
+        );
+    }
+
+    #[test]
+    fn a_branch_tag_is_djangos_too() {
+        assert_eq!(
+            highlight("{% empty %}"),
+            ["operator:{%", "keyword+defaultLibrary:empty", "operator:%}"]
+        );
+    }
+
+    #[test]
+    fn a_projects_own_tag_is_not_marked_as_djangos() {
+        assert_eq!(
+            highlight("{% render_bundle 'main' %}"),
+            [
+                "operator:{%",
+                "keyword:render_bundle",
+                "string:'main'",
+                "operator:%}",
+            ]
+        );
+    }
+
+    #[test]
+    fn a_loop_variable_is_a_definition_where_it_is_bound() {
+        assert_eq!(
+            highlight("{% for book in books %}{{ book }}{% endfor %}"),
+            [
+                "operator:{%",
+                "keyword+defaultLibrary:for",
+                "variable+definition:book",
+                "keyword:in",
+                "variable:books",
+                "operator:%}",
+                "operator:{{",
+                "variable:book",
+                "operator:}}",
+                "operator:{%",
+                "keyword+defaultLibrary:endfor",
+                "operator:%}",
+            ]
+        );
+    }
+
+    #[test]
+    fn a_block_name_is_highlighted_as_the_fragment_it_names() {
+        assert_eq!(
+            highlight("{% block content %}{% endblock %}"),
+            [
+                "operator:{%",
+                "keyword+defaultLibrary:block",
+                "function+definition:content",
+                "operator:%}",
+                "operator:{%",
+                "keyword+defaultLibrary:endblock",
+                "operator:%}",
+            ]
+        );
+    }
+
+    #[test]
+    fn a_partial_definition_and_its_use() {
+        assert_eq!(
+            highlight("{% partialdef card %}{% endpartialdef %}{% partial card %}"),
+            [
+                "operator:{%",
+                "keyword+defaultLibrary:partialdef",
+                "function+definition:card",
+                "operator:%}",
+                "operator:{%",
+                "keyword+defaultLibrary:endpartialdef",
+                "operator:%}",
+                "operator:{%",
+                "keyword+defaultLibrary:partial",
+                "variable:card",
+                "operator:%}",
+            ]
+        );
+    }
+
+    #[test]
+    fn keyword_arguments_strings_numbers_and_constants() {
+        assert_eq!(
+            highlight("{% include 'a.html' with n=3 flag=True %}"),
+            [
+                "operator:{%",
+                "keyword+defaultLibrary:include",
+                "string:'a.html'",
+                "keyword:with",
+                "parameter:n",
+                "operator:=",
+                "number:3",
+                "parameter:flag",
+                "operator:=",
+                "builtinConstant:True",
+                "operator:%}",
+            ]
+        );
+    }
+
+    #[test]
+    fn comments() {
+        assert_eq!(
+            highlight("{# a #}{% comment %}b{% endcomment %}"),
+            [
+                "operator:{#",
+                "comment: a ",
+                "operator:#}",
+                "operator:{%",
+                "keyword+defaultLibrary:comment",
+                "operator:%}",
+                "comment:b",
+                "operator:{%",
+                "keyword+defaultLibrary:endcomment",
+                "operator:%}",
+            ]
+        );
+    }
+
+    #[test]
+    fn a_range_restricts_the_tokens_to_what_it_touches() {
+        let source = "{{ a }}{{ b }}";
+        let index = TemplateIndex::from_source(source);
+        let end = u32::try_from(source.len()).unwrap();
+
+        let tokens = semantic_tokens(&index, source, Some(TextRange::new(7.into(), end.into())));
+        assert_eq!(
+            tokens
+                .iter()
+                .map(|token| &source[token.range])
+                .collect::<Vec<_>>(),
+            ["{{", "b", "}}"]
+        );
+    }
+
+    #[test]
+    fn tokens_come_back_in_source_order() {
+        let source = "{% for x in y %}{{ x.z|upper }}{% endfor %}";
+        let index = TemplateIndex::from_source(source);
+
+        let tokens = semantic_tokens(&index, source, None);
+        assert!(
+            tokens
+                .windows(2)
+                .all(|pair| pair[0].range.start() <= pair[1].range.start()),
+            "the encoder relies on tokens arriving sorted"
+        );
+    }
+}
diff --git a/crates/ty_ide/src/lib.rs b/crates/ty_ide/src/lib.rs
index d0b27b0ca2..2ad97b70ab 100644
--- a/crates/ty_ide/src/lib.rs
+++ b/crates/ty_ide/src/lib.rs
@@ -6,6 +6,7 @@ mod all_symbols;
 mod call_hierarchy;
 mod code_action;
 mod completion;
+mod django_template;
 mod doc_highlights;
 mod docstring;
 mod document_symbols;
@@ -39,6 +40,10 @@ pub use completion::{
     Completion, CompletionCapabilities, CompletionInsertTextFormat, CompletionKind,
     CompletionSettings, completion,
 };
+pub use django_template::{
+    TemplateCompletion, TemplateEdit, django_template_completions, django_template_goto_definition,
+    django_template_semantic_tokens, is_django_template_path,
+};
 pub use doc_highlights::document_highlights;
 pub use document_symbols::document_symbols;
 pub use find_references::find_references;
@@ -240,8 +245,7 @@ impl NavigationTargets {
         self.0.iter()
     }
 
-    #[cfg(test)]
-    fn is_empty(&self) -> bool {
+    pub fn is_empty(&self) -> bool {
         self.0.is_empty()
     }
 
diff --git a/crates/ty_ide/src/semantic_tokens.rs b/crates/ty_ide/src/semantic_tokens.rs
index 48b2ffcef4..d948d1f64a 100644
--- a/crates/ty_ide/src/semantic_tokens.rs
+++ b/crates/ty_ide/src/semantic_tokens.rs
@@ -79,11 +79,19 @@ pub enum SemanticTokenType {
     Decorator,
     BuiltinConstant,
     TypeParameter,
+    // New variants must be appended, never inserted: a token type's position in
+    // this enum is the index the LSP wire format sends for it, and the client
+    // resolves that index against the legend `all` produces.
+    /// Only produced for django templates, which have comments of their own.
+    Comment,
+    /// Only produced for django templates, whose `|`, `:` and delimiters have no
+    /// python counterpart worth colouring.
+    Operator,
 }
 
 impl SemanticTokenType {
     /// Returns all supported semantic token types as enum variants.
-    pub const fn all() -> [SemanticTokenType; 15] {
+    pub const fn all() -> [SemanticTokenType; 17] {
         [
             SemanticTokenType::Namespace,
             SemanticTokenType::Class,
@@ -100,6 +108,8 @@ impl SemanticTokenType {
             SemanticTokenType::Decorator,
             SemanticTokenType::BuiltinConstant,
             SemanticTokenType::TypeParameter,
+            SemanticTokenType::Comment,
+            SemanticTokenType::Operator,
         ]
     }
 
@@ -127,6 +137,8 @@ impl SemanticTokenType {
             SemanticTokenType::Decorator => "decorator",
             SemanticTokenType::BuiltinConstant => "builtinConstant",
             SemanticTokenType::TypeParameter => "typeParameter",
+            SemanticTokenType::Comment => "comment",
+            SemanticTokenType::Operator => "operator",
         }
     }
 }
@@ -139,6 +151,10 @@ bitflags! {
         const READONLY = 1 << 1;
         const ASYNC = 1 << 2;
         const DOCUMENTATION = 1 << 3;
+        /// The name is the language's own rather than the project's. Only
+        /// produced for django templates, where it separates a builtin tag or
+        /// filter from one the project registered.
+        const DEFAULT_LIBRARY = 1 << 4;
     }
 }
 
@@ -150,8 +166,16 @@ impl SemanticTokenModifier {
     /// clients can use these for standardized color coding and syntax
     /// highlighting. For details, refer to this LSP specification:
     /// <https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification/#semanticTokenModifiers>
+    /// New modifiers must be appended, never inserted: a modifier's bit position
+    /// is the index the LSP wire format sends for it.
     pub fn all_names() -> Vec<&'static str> {
-        vec!["definition", "readonly", "async", "documentation"]
+        vec![
+            "definition",
+            "readonly",
+            "async",
+            "documentation",
+            "defaultLibrary",
+        ]
     }
 }
 
diff --git a/crates/ty_python_semantic/src/types/ide_support.rs b/crates/ty_python_semantic/src/types/ide_support.rs
index 572bbeeb00..46720b73b0 100644
--- a/crates/ty_python_semantic/src/types/ide_support.rs
+++ b/crates/ty_python_semantic/src/types/ide_support.rs
@@ -2438,6 +2438,16 @@ pub fn type_parameter_names<'db>(db: &'db dyn Db, ty: Type<'db>) -> Option<Vec<N
     )
 }
 
+/// The type a `for` loop over a value of type `ty` binds, or `None` when `ty`
+/// isn't iterable at all.
+///
+/// Written for django templates, whose `{% for %}` has no python expression an
+/// IDE could ask the inference engine about: the loop lives in a template file,
+/// so the element type has to be derived from the iterable's type directly.
+pub fn iterable_element_type<'db>(db: &'db dyn Db, ty: Type<'db>) -> Option<Type<'db>> {
+    Some(ty.try_iterate(db).ok()?.homogeneous_element_type(db))
+}
+
 /// The extra arms the typing spec's numeric promotion adds to a type expression
 /// that already evaluated to `ty`, rendered as they would be spelled.
 ///
diff --git a/crates/ty_server/src/capabilities.rs b/crates/ty_server/src/capabilities.rs
index 5b0a838622..3c13131959 100644
--- a/crates/ty_server/src/capabilities.rs
+++ b/crates/ty_server/src/capabilities.rs
@@ -472,7 +472,21 @@ pub(crate) fn server_capabilities(
             .into(),
         ),
         completion_provider: Some(CompletionOptions {
-            trigger_characters: Some(vec!['.'.to_string(), '"'.to_string(), '\''.to_string()]),
+            // `%`, `|` and `{` are here for django templates: the interesting
+            // positions in a template are right after `{%`, `{{` and `|`, and
+            // none of them is a word character the client would trigger on by
+            // itself. LSP has no way to vary these per language, so python
+            // documents see them too — harmlessly, since a completion request
+            // there is answered from the cursor's position rather than from
+            // whichever character triggered it.
+            trigger_characters: Some(vec![
+                '.'.to_string(),
+                '"'.to_string(),
+                '\''.to_string(),
+                '{'.to_string(),
+                '%'.to_string(),
+                '|'.to_string(),
+            ]),
             ..Default::default()
         }),
         selection_range_provider: Some(true.into()),
diff --git a/crates/ty_server/src/document/text_document.rs b/crates/ty_server/src/document/text_document.rs
index 95e0da8a73..0e4621fcdf 100644
--- a/crates/ty_server/src/document/text_document.rs
+++ b/crates/ty_server/src/document/text_document.rs
@@ -5,6 +5,7 @@ use lsp_types::{
 use ruff_source_file::LineIndex;
 
 use crate::PositionEncoding;
+use crate::document::DocumentKey;
 use crate::document::range::lsp_range_to_text_range;
 use crate::system::AnySystemPath;
 
@@ -36,16 +37,36 @@ pub struct TextDocument {
 #[derive(Debug, Copy, Clone, PartialEq, Eq)]
 pub enum LanguageId {
     Python,
+    /// A django template. Not python, but the server still has language services
+    /// for it — see [`ty_ide::django_template_completions`].
+    DjangoTemplate,
     Other,
 }
 
-impl From<LanguageKind> for LanguageId {
-    fn from(language_id: LanguageKind) -> Self {
+impl LanguageId {
+    /// The language of a document the client has opened at `path`.
+    ///
+    /// Editors disagree about what to call a django template: the vs code django
+    /// extensions use `django-html`, vim uses `htmldjango`, and a great many
+    /// setups just call it `html`. That last case is why the path is consulted
+    /// at all — a `.html` file inside a `templates` directory is a django
+    /// template whatever the client chose to call it.
+    pub(crate) fn new(language_id: &LanguageKind, path: &AnySystemPath) -> Self {
         match language_id.as_str() {
             "python" | "by" => Self::Python,
-            _ => Self::Other,
+            "django-html" | "django-txt" | "htmldjango" | "jinja-html" | "django" => {
+                Self::DjangoTemplate
+            }
+            _ => match path.as_system() {
+                Some(path) if ty_ide::is_django_template_path(path) => Self::DjangoTemplate,
+                _ => Self::Other,
+            },
         }
     }
+
+    pub(crate) const fn is_django_template(self) -> bool {
+        matches!(self, Self::DjangoTemplate)
+    }
 }
 
 impl TextDocument {
@@ -53,13 +74,16 @@ impl TextDocument {
         uri: Uri,
         contents: String,
         version: DocumentVersion,
-        language_id: LanguageKind,
+        language_id: &LanguageKind,
     ) -> Self {
+        let language_id =
+            LanguageId::new(language_id, &DocumentKey::from_uri(&uri).into_file_path());
+
         Self {
             uri,
             contents,
             version,
-            language_id: LanguageId::from(language_id),
+            language_id,
             notebook: None,
         }
     }
@@ -183,7 +207,7 @@ def interface():
 "#
             .to_string(),
             0,
-            LanguageKind::Python,
+            &LanguageKind::Python,
         );
 
         // Add an `s`, remove it again (back to the original code), and then re-add the `s`
diff --git a/crates/ty_server/src/server/api/diagnostics.rs b/crates/ty_server/src/server/api/diagnostics.rs
index 6c1236b2c7..bacde9c1ac 100644
--- a/crates/ty_server/src/server/api/diagnostics.rs
+++ b/crates/ty_server/src/server/api/diagnostics.rs
@@ -392,6 +392,14 @@ pub(super) fn compute_diagnostics(
     document: &DocumentHandle,
     encoding: PositionEncoding,
 ) -> Option<Diagnostics> {
+    // A django template is not python. Nothing here would report anything for
+    // one — the type checker never has it in its file set — but going through
+    // the motions would still parse an html file as python for the hints, so it
+    // is turned away up front.
+    if document.is_django_template() {
+        return None;
+    }
+
     let Some(file) = document.notebook_or_file(db) else {
         tracing::info!(
             "No file found for snapshot for `{}`",
diff --git a/crates/ty_server/src/server/api/notifications/did_open.rs b/crates/ty_server/src/server/api/notifications/did_open.rs
index 3c67363209..55b2adf502 100644
--- a/crates/ty_server/src/server/api/notifications/did_open.rs
+++ b/crates/ty_server/src/server/api/notifications/did_open.rs
@@ -29,7 +29,7 @@ impl SyncNotificationHandler for DidOpenTextDocumentHandler {
                 },
         } = params;
 
-        let text_doc = TextDocument::new(uri, text, version, language_id);
+        let text_doc = TextDocument::new(uri, text, version, &language_id);
         let document = session.open_text_document(text_doc);
         publish_diagnostics_if_needed(&document, session, client);
 
diff --git a/crates/ty_server/src/server/api/notifications/did_open_notebook.rs b/crates/ty_server/src/server/api/notifications/did_open_notebook.rs
index c76a1bbfe4..8f2607479f 100644
--- a/crates/ty_server/src/server/api/notifications/did_open_notebook.rs
+++ b/crates/ty_server/src/server/api/notifications/did_open_notebook.rs
@@ -39,7 +39,7 @@ impl SyncNotificationHandler for DidOpenNotebookHandler {
 
         for cell in params.cell_text_documents {
             let cell_document =
-                TextDocument::new(cell.uri, cell.text, cell.version, cell.language_id)
+                TextDocument::new(cell.uri, cell.text, cell.version, &cell.language_id)
                     .with_notebook(notebook_path.clone());
             session.open_text_document(cell_document);
         }
diff --git a/crates/ty_server/src/server/api/requests/completion.rs b/crates/ty_server/src/server/api/requests/completion.rs
index 90c4975580..c479c58517 100644
--- a/crates/ty_server/src/server/api/requests/completion.rs
+++ b/crates/ty_server/src/server/api/requests/completion.rs
@@ -56,6 +56,10 @@ impl BackgroundDocumentRequestHandler for CompletionRequestHandler {
         ) else {
             return Ok(None);
         };
+        if snapshot.is_django_template() {
+            return Ok(django_template_completions(db, snapshot, file, offset));
+        }
+
         let client_capabilities = snapshot.resolved_client_capabilities();
         let completions = completion(
             db,
@@ -167,6 +171,92 @@ impl RetriableRequestHandler for CompletionRequestHandler {
     const RETRY_ON_CANCELLATION: bool = true;
 }
 
+/// The completion response for a django template document.
+///
+/// Unlike the python ones, every template completion carries the range it
+/// replaces: a template path or a namespaced url name is not a word by any
+/// client's definition of one, so leaving the replacement to the client would
+/// mangle them.
+fn django_template_completions(
+    db: &ProjectDatabase,
+    snapshot: &DocumentSnapshot,
+    file: ruff_db::files::File,
+    offset: ruff_text_size::TextSize,
+) -> Option<CompletionResponse> {
+    let completions = ty_ide::django_template_completions(db, file, offset);
+    if completions.is_empty() {
+        return None;
+    }
+
+    // Safety: we just checked that completions is not empty.
+    let max_index_len = OneIndexed::new(completions.len()).unwrap().digits().get();
+    let to_edit = |edit: &ty_ide::TemplateEdit| {
+        Some(TextEdit {
+            range: edit
+                .range
+                .to_lsp_range(db, file, snapshot.encoding())?
+                .local_range(),
+            new_text: edit.text.clone(),
+        })
+    };
+
+    let items: Vec<CompletionItem> = completions
+        .into_iter()
+        .enumerate()
+        .map(|(index, completion)| {
+            let text_edit = completion
+                .range
+                .to_lsp_range(db, file, snapshot.encoding())
+                .map(|range| {
+                    lsp_types::CompletionItemTextEdit::TextEdit(TextEdit {
+                        range: range.local_range(),
+                        new_text: completion
+                            .insert
+                            .clone()
+                            .unwrap_or_else(|| completion.label.clone()),
+                    })
+                });
+
+            let documentation = completion.documentation.map(|value| {
+                let kind = if snapshot
+                    .resolved_client_capabilities()
+                    .prefers_markdown_in_completion()
+                {
+                    lsp_types::MarkupKind::Markdown
+                } else {
+                    lsp_types::MarkupKind::PlainText
+                };
+
+                Documentation::MarkupContent(lsp_types::MarkupContent { kind, value })
+            });
+
+            CompletionItem {
+                label: completion.label,
+                kind: Some(ty_kind_to_lsp_kind(completion.kind)),
+                // the order the suggestions arrive in is the order they are
+                // meant to be shown in
+                sort_text: Some(format!("{index:-max_index_len$}")),
+                detail: completion.detail,
+                documentation,
+                text_edit,
+                additional_text_edits: completion
+                    .additional_edit
+                    .as_ref()
+                    .and_then(to_edit)
+                    .map(|edit| vec![edit]),
+                ..Default::default()
+            }
+        })
+        .collect();
+
+    Some(CompletionResponse::CompletionList(CompletionList {
+        is_incomplete: true,
+        items,
+        item_defaults: None,
+        apply_kind: None,
+    }))
+}
+
 fn ty_kind_to_lsp_kind(kind: CompletionKind) -> CompletionItemKind {
     // Gimme my dang globs in tight scopes!
     #[allow(clippy::enum_glob_use)]
diff --git a/crates/ty_server/src/server/api/requests/goto_definition.rs b/crates/ty_server/src/server/api/requests/goto_definition.rs
index 88d989705e..f849d41d3d 100644
--- a/crates/ty_server/src/server/api/requests/goto_definition.rs
+++ b/crates/ty_server/src/server/api/requests/goto_definition.rs
@@ -2,7 +2,7 @@ use std::borrow::Cow;
 
 use lsp_types::DefinitionRequest;
 use lsp_types::{DefinitionParams, DefinitionResponse, Uri};
-use ty_ide::goto_definition;
+use ty_ide::{django_template_goto_definition, goto_definition};
 use ty_project::ProjectDatabase;
 
 use crate::document::{PositionExt, ToLink};
@@ -49,7 +49,13 @@ impl BackgroundDocumentRequestHandler for GotoDefinitionRequestHandler {
             return Ok(None);
         };
 
-        let Some(ranged) = goto_definition(db, file, offset) else {
+        let definition = if snapshot.is_django_template() {
+            django_template_goto_definition(db, file, offset)
+        } else {
+            goto_definition(db, file, offset)
+        };
+
+        let Some(ranged) = definition else {
             return Ok(None);
         };
 
diff --git a/crates/ty_server/src/server/api/requests/semantic_tokens.rs b/crates/ty_server/src/server/api/requests/semantic_tokens.rs
index 2dac5eb2f5..06c21ff5ee 100644
--- a/crates/ty_server/src/server/api/requests/semantic_tokens.rs
+++ b/crates/ty_server/src/server/api/requests/semantic_tokens.rs
@@ -46,7 +46,8 @@ impl BackgroundDocumentRequestHandler for SemanticTokensRequestHandler {
         // because all ranges in the response must be within this **this document**.
         let mut cell_range = None;
 
-        if snapshot.document().is_cell()
+        if !snapshot.is_django_template()
+            && snapshot.document().is_cell()
             && let Some(notebook_document) = db.notebook_document(file)
             && let Some(notebook) = source_text(db, file).as_notebook()
         {
@@ -63,6 +64,7 @@ impl BackgroundDocumentRequestHandler for SemanticTokensRequestHandler {
             snapshot
                 .resolved_client_capabilities()
                 .supports_multiline_semantic_tokens(),
+            snapshot.is_django_template(),
         );
 
         Ok(Some(SemanticTokens {
diff --git a/crates/ty_server/src/server/api/requests/semantic_tokens_range.rs b/crates/ty_server/src/server/api/requests/semantic_tokens_range.rs
index 7951a5ee9c..7ea1ce3891 100644
--- a/crates/ty_server/src/server/api/requests/semantic_tokens_range.rs
+++ b/crates/ty_server/src/server/api/requests/semantic_tokens_range.rs
@@ -56,6 +56,7 @@ impl BackgroundDocumentRequestHandler for SemanticTokensRangeRequestHandler {
             snapshot
                 .resolved_client_capabilities()
                 .supports_multiline_semantic_tokens(),
+            snapshot.is_django_template(),
         );
 
         Ok(Some(SemanticTokens {
diff --git a/crates/ty_server/src/server/api/semantic_tokens.rs b/crates/ty_server/src/server/api/semantic_tokens.rs
index 07e4d5432b..09ccfb04c5 100644
--- a/crates/ty_server/src/server/api/semantic_tokens.rs
+++ b/crates/ty_server/src/server/api/semantic_tokens.rs
@@ -2,23 +2,33 @@ use lsp_types::SemanticToken;
 use ruff_db::source::{line_index, source_text};
 use ruff_source_file::OneIndexed;
 use ruff_text_size::{Ranged, TextRange};
-use ty_ide::{SemanticTokenModifier, SemanticTokenType, semantic_tokens};
+use ty_ide::{
+    SemanticTokenModifier, SemanticTokenType, django_template_semantic_tokens, semantic_tokens,
+};
 use ty_project::ProjectDatabase;
 
 use crate::document::{PositionEncoding, ToRangeExt};
 
 /// Common logic for generating semantic tokens, either for full document or a specific range.
 /// If no range is provided, the entire file is processed.
+///
+/// The two languages produce their tokens differently but encode them
+/// identically, because they share one legend.
 pub(crate) fn generate_semantic_tokens(
     db: &ProjectDatabase,
     file: ruff_db::files::File,
     range: Option<TextRange>,
     encoding: PositionEncoding,
     multiline_token_support: bool,
+    django_template: bool,
 ) -> Vec<SemanticToken> {
     let source = source_text(db, file);
     let line_index = line_index(db, file);
-    let semantic_token_data = semantic_tokens(db, file, range);
+    let semantic_token_data = if django_template {
+        django_template_semantic_tokens(db, file, range)
+    } else {
+        semantic_tokens(db, file, range)
+    };
 
     let mut encoder = Encoder {
         tokens: Vec::with_capacity(semantic_token_data.len()),
diff --git a/crates/ty_server/src/session.rs b/crates/ty_server/src/session.rs
index 8493677cb2..aa28a20443 100644
--- a/crates/ty_server/src/session.rs
+++ b/crates/ty_server/src/session.rs
@@ -1217,10 +1217,15 @@ impl Session {
                 .is_none_or(|file| !file.exists(db))
         });
 
-        // When we know the document isn't a Python source file
-        // then we'll avoid adding it to the project. (But we
-        // still track it as part of the index.)
-        let is_not_python = matches!(language_id, Some(LanguageId::Other));
+        // A document in a language the server has no services at all for is
+        // tracked by the index but never enters the project.
+        let is_unsupported = matches!(language_id, Some(LanguageId::Other));
+
+        // A django template does have language services, so its `File` has to be
+        // interned for its source to be readable — but it is not python, so it is
+        // never added to the project's open-file set. That is what keeps the type
+        // checker from ever being handed a `.html` file.
+        let is_template = language_id.is_some_and(LanguageId::is_django_template);
 
         match path {
             AnySystemPath::System(system_path) => {
@@ -1234,7 +1239,7 @@ impl Session {
                 };
                 self.apply_changes(path, &[event]);
 
-                if is_not_python {
+                if is_unsupported {
                     return;
                 }
 
@@ -1245,7 +1250,7 @@ impl Session {
 
                         // Only mark this file as open if it's part of the project.
                         // This ensures that we don't show diagnostics for files outside the project.
-                        if project.is_file_included(db, system_path).is_included() {
+                        if !is_template && project.is_file_included(db, system_path).is_included() {
                             project.open_file(db, file);
                         }
                     }
@@ -1253,13 +1258,15 @@ impl Session {
                 }
             }
             AnySystemPath::SystemVirtual(virtual_path) => {
-                if is_not_python {
+                if is_unsupported {
                     return;
                 }
 
                 let db = self.project_db_mut(path);
                 let virtual_file = db.files().virtual_file(db, virtual_path);
-                db.project().open_file(db, virtual_file.file());
+                if !is_template {
+                    db.project().open_file(db, virtual_file.file());
+                }
             }
         }
 
@@ -1418,6 +1425,11 @@ impl DocumentSnapshot {
     pub(crate) fn client_name(&self) -> ClientName {
         self.client_name
     }
+
+    /// Whether this document is a django template rather than python.
+    pub(crate) fn is_django_template(&self) -> bool {
+        self.document.is_django_template()
+    }
 }
 
 /// An immutable snapshot of the current state of [`Session`].
@@ -1688,6 +1700,9 @@ pub(crate) enum DocumentHandle {
         uri: lsp_types::Uri,
         path: AnySystemPath,
         version: DocumentVersion,
+        /// What the document is written in, which decides whether a request for
+        /// it is answered by the python services or the django template ones.
+        language_id: LanguageId,
     },
     Notebook {
         uri: lsp_types::Uri,
@@ -1708,6 +1723,7 @@ impl DocumentHandle {
                 version: document.version(),
                 uri: document.uri().clone(),
                 path: DocumentKey::from_uri(document.uri()).into_file_path(),
+                language_id: document.language_id(),
             },
             Some(notebook) => Self::Cell {
                 notebook_path: notebook.clone(),
@@ -1794,6 +1810,21 @@ impl DocumentHandle {
         }
     }
 
+    /// What this document is written in.
+    ///
+    /// A notebook and its cells are always python; only a plain text document
+    /// can be anything else.
+    pub(crate) fn language_id(&self) -> LanguageId {
+        match self {
+            Self::Text { language_id, .. } => *language_id,
+            Self::Notebook { .. } | Self::Cell { .. } => LanguageId::Python,
+        }
+    }
+
+    pub(crate) fn is_django_template(&self) -> bool {
+        self.language_id().is_django_template()
+    }
+
     pub(crate) fn is_cell(&self) -> bool {
         matches!(self, Self::Cell { .. })
     }
diff --git a/crates/ty_server/src/session/index.rs b/crates/ty_server/src/session/index.rs
index 3360f339e9..0576a46ed7 100644
--- a/crates/ty_server/src/session/index.rs
+++ b/crates/ty_server/src/session/index.rs
@@ -126,7 +126,7 @@ impl Index {
                         opened_cell.uri,
                         opened_cell.text,
                         opened_cell.version,
-                        opened_cell.language_id,
+                        &opened_cell.language_id,
                     )
                     .with_notebook(notebook_path.clone())
                     .into(),
diff --git a/crates/ty_server/src/system.rs b/crates/ty_server/src/system.rs
index e35fb030cb..31ed446713 100644
--- a/crates/ty_server/src/system.rs
+++ b/crates/ty_server/src/system.rs
@@ -138,7 +138,9 @@ impl LSPSystem {
                         source_type => source_type,
                     })
                 }
-                LanguageId::Other => None,
+                // a django template is served to the ide like any other document,
+                // but it is not python and must never be parsed as such
+                LanguageId::DjangoTemplate | LanguageId::Other => None,
             },
             Document::Notebook(_) => Some(PySourceType::Ipynb),
         }
diff --git a/crates/ty_server/tests/e2e/django_templates.rs b/crates/ty_server/tests/e2e/django_templates.rs
new file mode 100644
index 0000000000..7f7f908f80
--- /dev/null
+++ b/crates/ty_server/tests/e2e/django_templates.rs
@@ -0,0 +1,259 @@
+//! end-to-end coverage of the django template language services
+//!
+//! the unit tests in `ty_ide` cover what each feature answers; these cover that a
+//! template document reaches those features at all — that the server recognises
+//! the language, keeps the type checker away from it, and routes its requests to
+//! the template implementations rather than the python ones.
+
+use anyhow::Result;
+use lsp_types::{
+    DocumentDiagnosticReport, LanguageKind, Position, TextDocumentIdentifier,
+    TextDocumentPositionParams,
+};
+use ruff_db::system::SystemPath;
+
+use crate::{TestServer, TestServerBuilder};
+
+const VIEWS: &str = "\
+from blog.models import Book
+
+
+def post(request):
+    return render(request, 'blog/post.html', {'book': Book()})
+";
+
+const MODELS: &str = "\
+class Author:
+    name: str
+
+
+class Book:
+    title: str
+    author: Author
+";
+
+const URLS: &str = "\
+app_name = 'blog'
+
+urlpatterns = [path('books/', index, name='index')]
+";
+
+const BASE: &str = "{% block content %}{% endblock %}\n";
+
+/// a project with a view, a model, a url configuration and a base template, plus
+/// the template under test
+fn server(template: &str) -> Result<TestServer> {
+    let mut server = TestServerBuilder::new()?
+        .with_workspace(SystemPath::new("src"), None)?
+        .with_file(SystemPath::new("src/blog/models.py"), MODELS)?
+        .with_file(SystemPath::new("src/blog/views.py"), VIEWS)?
+        .with_file(SystemPath::new("src/blog/urls.py"), URLS)?
+        .with_file(SystemPath::new("src/blog/templates/blog/base.html"), BASE)?
+        .with_file(
+            SystemPath::new("src/blog/templates/blog/post.html"),
+            template,
+        )?
+        .build()
+        .wait_until_workspaces_are_initialized();
+
+    server.open_text_document_as(
+        SystemPath::new("src/blog/templates/blog/post.html"),
+        template,
+        1,
+        LanguageKind::new("django-html"),
+    );
+
+    Ok(server)
+}
+
+fn template_uri(server: &TestServer) -> lsp_types::Uri {
+    server.file_uri(SystemPath::new("src/blog/templates/blog/post.html"))
+}
+
+#[test]
+fn a_template_completes_the_views_context() -> Result<()> {
+    let mut server = server("{{  }}\n")?;
+    let uri = template_uri(&server);
+
+    let completions = server.completion_request(&uri, Position::new(0, 3));
+    let labels: Vec<_> = completions
+        .iter()
+        .map(|completion| completion.label.as_str())
+        .collect();
+
+    assert_eq!(labels, ["book"]);
+
+    Ok(())
+}
+
+#[test]
+fn a_template_completes_the_attributes_of_a_context_variable() -> Result<()> {
+    let mut server = server("{{ book. }}\n")?;
+    let uri = template_uri(&server);
+
+    let completions = server.completion_request(&uri, Position::new(0, 8));
+    let labels: Vec<_> = completions
+        .iter()
+        .map(|completion| completion.label.as_str())
+        .collect();
+
+    assert_eq!(labels, ["author", "title"]);
+
+    Ok(())
+}
+
+#[test]
+fn a_template_completes_tag_names() -> Result<()> {
+    let mut server = server("{%  %}\n")?;
+    let uri = template_uri(&server);
+
+    let completions = server.completion_request(&uri, Position::new(0, 3));
+    let labels: Vec<_> = completions
+        .iter()
+        .map(|completion| completion.label.as_str())
+        .collect();
+
+    assert!(labels.contains(&"extends"), "got {labels:?}");
+    assert!(labels.contains(&"partialdef"), "got {labels:?}");
+
+    Ok(())
+}
+
+#[test]
+fn a_template_completion_replaces_an_explicit_range() -> Result<()> {
+    // the client is told exactly what to replace, because a template name is not
+    // a word by any client's definition of one
+    let mut server = server("{% extends '' %}\n")?;
+    let uri = template_uri(&server);
+
+    let completions = server.completion_request(&uri, Position::new(0, 12));
+    let first = completions.first().expect("a template to be offered");
+
+    assert!(
+        matches!(
+            first.text_edit,
+            Some(lsp_types::CompletionItemTextEdit::TextEdit(_))
+        ),
+        "got {:?}",
+        first.text_edit
+    );
+
+    Ok(())
+}
+
+#[test]
+fn a_template_produces_semantic_tokens() -> Result<()> {
+    let mut server = server("<p>{{ book.title }}</p>\n")?;
+    let uri = template_uri(&server);
+
+    let tokens = server
+        .semantic_tokens_full_request(&uri)
+        .expect("a template to be highlighted");
+
+    // `{{`, `book`, `.`, `title`, `}}` — the markup around them is the client's
+    assert_eq!(tokens.data.len(), 5);
+
+    Ok(())
+}
+
+#[test]
+fn a_template_navigates_to_the_template_it_extends() -> Result<()> {
+    let mut server = server("{% extends 'blog/base.html' %}\n")?;
+    let uri = template_uri(&server);
+
+    let response = server
+        .send_request_await::<lsp_types::DefinitionRequest>(lsp_types::DefinitionParams {
+            text_document_position_params: TextDocumentPositionParams {
+                text_document: TextDocumentIdentifier { uri },
+                position: Position::new(0, 15),
+            },
+            work_done_progress_params: lsp_types::WorkDoneProgressParams::default(),
+            partial_result_params: lsp_types::PartialResultParams::default(),
+        })
+        .expect("a definition response");
+
+    let rendered = format!("{response:?}");
+    assert!(rendered.contains("base.html"), "got {rendered}");
+
+    Ok(())
+}
+
+#[test]
+fn a_template_is_never_type_checked_as_python() -> Result<()> {
+    // every line of this would be a python syntax error
+    let mut server = server("<!doctype html>\n<p>{{ book.title }}</p>\n")?;
+
+    let report = server
+        .document_diagnostic_request(SystemPath::new("src/blog/templates/blog/post.html"), None);
+
+    let DocumentDiagnosticReport::RelatedFullDocumentDiagnosticReport(report) = report else {
+        panic!("expected a full report, got {report:?}");
+    };
+    assert!(
+        report.full_document_diagnostic_report.items.is_empty(),
+        "got {:?}",
+        report.full_document_diagnostic_report.items
+    );
+
+    Ok(())
+}
+
+#[test]
+fn an_html_file_outside_a_templates_directory_is_not_a_template() -> Result<()> {
+    // the client called it `html`, and nothing about its path says otherwise, so
+    // the server must not read it as a django template
+    let page = SystemPath::new("src/static/index.html");
+    let content = "{%  %}\n";
+
+    let mut server = TestServerBuilder::new()?
+        .with_workspace(SystemPath::new("src"), None)?
+        .with_file(SystemPath::new("src/blog/models.py"), MODELS)?
+        .with_file(SystemPath::new("src/blog/views.py"), VIEWS)?
+        .with_file(page, content)?
+        .build()
+        .wait_until_workspaces_are_initialized();
+
+    server.open_text_document_as(page, content, 1, LanguageKind::new("html"));
+
+    let completions = server.completion_request(&server.file_uri(page), Position::new(0, 3));
+    let labels: Vec<_> = completions
+        .iter()
+        .map(|completion| completion.label.as_str())
+        .collect();
+
+    assert!(
+        !labels.contains(&"partialdef"),
+        "django tags were offered in a plain html file: {labels:?}"
+    );
+
+    Ok(())
+}
+
+#[test]
+fn an_html_file_inside_a_templates_directory_is_a_template_whatever_the_client_calls_it()
+-> Result<()> {
+    // vs code reports a plain `.html` language for most django projects, so the
+    // path has to be enough on its own
+    let template = "{%  %}\n";
+    let path = SystemPath::new("src/blog/templates/blog/post.html");
+
+    let mut server = TestServerBuilder::new()?
+        .with_workspace(SystemPath::new("src"), None)?
+        .with_file(SystemPath::new("src/blog/models.py"), MODELS)?
+        .with_file(SystemPath::new("src/blog/views.py"), VIEWS)?
+        .with_file(path, template)?
+        .build()
+        .wait_until_workspaces_are_initialized();
+
+    server.open_text_document_as(path, template, 1, LanguageKind::new("html"));
+
+    let completions = server.completion_request(&server.file_uri(path), Position::new(0, 3));
+    let labels: Vec<_> = completions
+        .iter()
+        .map(|completion| completion.label.as_str())
+        .collect();
+
+    assert!(labels.contains(&"partialdef"), "got {labels:?}");
+
+    Ok(())
+}
diff --git a/crates/ty_server/tests/e2e/main.rs b/crates/ty_server/tests/e2e/main.rs
index 79f7f85e97..ffaf865f97 100644
--- a/crates/ty_server/tests/e2e/main.rs
+++ b/crates/ty_server/tests/e2e/main.rs
@@ -32,6 +32,7 @@ mod code_actions;
 mod commands;
 mod completions;
 mod configuration;
+mod django_templates;
 mod folding_range;
 mod hover;
 mod initialize;
@@ -796,11 +797,22 @@ impl TestServer {
         path: impl AsRef<SystemPath>,
         content: impl AsRef<str>,
         version: i32,
+    ) {
+        self.open_text_document_as(path, content, version, LanguageKind::Python);
+    }
+
+    /// Send a `textDocument/didOpen` for a document in the given language.
+    pub(crate) fn open_text_document_as(
+        &mut self,
+        path: impl AsRef<SystemPath>,
+        content: impl AsRef<str>,
+        version: i32,
+        language_id: LanguageKind,
     ) {
         let params = DidOpenTextDocumentParams {
             text_document: TextDocumentItem {
                 uri: self.file_uri(path),
-                language_id: LanguageKind::Python,
+                language_id,
                 version,
                 text: content.as_ref().to_string(),
             },
diff --git a/crates/ty_server/tests/e2e/snapshots/e2e__initialize__initialization.snap b/crates/ty_server/tests/e2e/snapshots/e2e__initialize__initialization.snap
index 2fbcab3bb6..58cd8e2ffd 100644
--- a/crates/ty_server/tests/e2e/snapshots/e2e__initialize__initialization.snap
+++ b/crates/ty_server/tests/e2e/snapshots/e2e__initialize__initialization.snap
@@ -28,7 +28,10 @@ expression: initialization_result
       "triggerCharacters": [
         ".",
         "\"",
-        "'"
+        "'",
+        "{",
+        "%",
+        "|"
       ]
     },
     "hoverProvider": true,
@@ -82,13 +85,16 @@ expression: initialization_result
           "number",
           "decorator",
           "builtinConstant",
-          "typeParameter"
+          "typeParameter",
+          "comment",
+          "operator"
         ],
         "tokenModifiers": [
           "definition",
           "readonly",
           "async",
-          "documentation"
+          "documentation",
+          "defaultLibrary"
         ]
       },
       "range": true,
diff --git a/crates/ty_server/tests/e2e/snapshots/e2e__initialize__initialization_with_workspace.snap b/crates/ty_server/tests/e2e/snapshots/e2e__initialize__initialization_with_workspace.snap
index 2fbcab3bb6..58cd8e2ffd 100644
--- a/crates/ty_server/tests/e2e/snapshots/e2e__initialize__initialization_with_workspace.snap
+++ b/crates/ty_server/tests/e2e/snapshots/e2e__initialize__initialization_with_workspace.snap
@@ -28,7 +28,10 @@ expression: initialization_result
       "triggerCharacters": [
         ".",
         "\"",
-        "'"
+        "'",
+        "{",
+        "%",
+        "|"
       ]
     },
     "hoverProvider": true,
@@ -82,13 +85,16 @@ expression: initialization_result
           "number",
           "decorator",
           "builtinConstant",
-          "typeParameter"
+          "typeParameter",
+          "comment",
+          "operator"
         ],
         "tokenModifiers": [
           "definition",
           "readonly",
           "async",
-          "documentation"
+          "documentation",
+          "defaultLibrary"
         ]
       },
       "range": true,
diff --git a/crates/ty_wasm/src/lib.rs b/crates/ty_wasm/src/lib.rs
index 1dfce5c61e..6edb68baff 100644
--- a/crates/ty_wasm/src/lib.rs
+++ b/crates/ty_wasm/src/lib.rs
@@ -1566,6 +1566,8 @@ pub enum SemanticTokenKind {
     Decorator,
     BuiltinConstant,
     TypeParameter,
+    Comment,
+    Operator,
 }
 
 impl From<ty_ide::SemanticTokenType> for SemanticTokenKind {
@@ -1586,6 +1588,8 @@ impl From<ty_ide::SemanticTokenType> for SemanticTokenKind {
             ty_ide::SemanticTokenType::Decorator => Self::Decorator,
             ty_ide::SemanticTokenType::BuiltinConstant => Self::BuiltinConstant,
             ty_ide::SemanticTokenType::TypeParameter => Self::TypeParameter,
+            ty_ide::SemanticTokenType::Comment => Self::Comment,
+            ty_ide::SemanticTokenType::Operator => Self::Operator,
         }
     }
 }
diff --git a/docs/basedpython/frameworks/django-templates.md b/docs/basedpython/frameworks/django-templates.md
new file mode 100644
index 0000000000..023cea7912
--- /dev/null
+++ b/docs/basedpython/frameworks/django-templates.md
@@ -0,0 +1,118 @@
+# django templates
+
+basedpython's language server understands django template files, not just the python around them. templates get syntax-aware highlighting, completions and go-to-definition, and all of it is joined up with the project's own django definitions — the models, views, urls and template tag libraries the type checker already knows about.
+
+## what the editor gets
+
+### completions
+
+what is offered depends on where the caret is.
+
+| position            | what is offered                                                                                                       |
+| ------------------- | --------------------------------------------------------------------------------------------------------------------- |
+| `{% ‸ %}`           | tag names: django's builtins, the project's own registered tags, and the `{% end… %}` that closes the block you're in |
+| `{{ x\|‸ }}`        | filter names: django's builtins and the project's own registered filters                                              |
+| `{{ ‸ }}`           | the variables the view puts in this template's context, plus the names the template itself binds                      |
+| `{{ book.‸ }}`      | the attributes of `book`'s type — for a django model, that's its fields                                               |
+| `{% extends '‸' %}` | the project's template paths                                                                                          |
+| `{% include '‸' %}` | the project's template paths                                                                                          |
+| `{% url '‸' %}`     | the project's route names, namespaced by `app_name`                                                                   |
+| `{% static '‸' %}`  | the files under the project's `static` directories                                                                    |
+| `{% load ‸ %}`      | the libraries not yet loaded, django's and the project's                                                              |
+| `{% block ‸ %}`     | the blocks the parent template defines and this one hasn't overridden yet                                             |
+| `{% partial ‸ %}`   | the fragments `{% partialdef %}` declares                                                                             |
+
+the tag that closes the block you're inside is always offered first, so `{% for %}` … `{%` completes to `{% endfor %}` in one keystroke, with `{% empty %}` right behind it.
+
+a tag or filter from a library the template hasn't loaded comes with the `{% load %}` it needs as an extra edit, written below the `{% extends %}` if there is one.
+
+### go-to-definition
+
+| on                                    | goes to                                                             |
+| ------------------------------------- | ------------------------------------------------------------------- |
+| `{% extends 'blog/base.html' %}`      | that template                                                       |
+| `{% include 'blog/card.html#item' %}` | that template, or the `{% partialdef item %}` inside it             |
+| `{% url 'blog:detail' %}`             | the `path(…, name='detail')` that names the route                   |
+| `{% partial card %}`                  | the `{% partialdef card %}` that declares it                        |
+| `{% block content %}`                 | the block it overrides, in the parent template                      |
+| `{% load blog_extras %}`              | the tag library module                                              |
+| a custom tag or filter name           | the python function registered under it                             |
+| `{{ book }}`                          | the context entry the view supplies, or the tag that binds the name |
+| `{{ book.title }}`                    | the type `title` is read off — for a model field, the model class   |
+
+### semantic highlighting
+
+the editor's own html grammar keeps the markup; the server adds what a grammar cannot know:
+
+- a tag or filter that is django's own is marked `defaultLibrary`, so the project's own tags are visibly distinct from the builtins
+- a name is a variable, an attribute of one, or a keyword argument, and each is coloured differently
+- the name a `{% for %}` or `{% with %}` binds is marked as a definition where it is bound
+- `{% block %}` and `{% partialdef %}` names read as the fragments they name, not as variables
+- `{% comment %}` bodies and `{# … #}` are comments; `{% verbatim %}` bodies are plain text
+
+## how a template's variables are found
+
+the chain runs from the template back to the type checker:
+
+```by
+# blog/views.py
+def post(request):
+    book = Book.objects.get(pk=1)
+    return render(request, "blog/post.html", {"book": book})
+```
+
+```django
+{# blog/templates/blog/post.html #}
+{{ book.author.name }}
+```
+
+the server finds the `render()` call that names `blog/post.html`, reads `book` out of its context dict, asks the type checker what that expression is — a `Book` — and then walks `author` and `name` through the model's fields. django's field machinery is already understood (see [django support](django.md)), so a `ForeignKey` traverses and a `null=True` field is optional, exactly as in python.
+
+the same works through the template's own bindings:
+
+```django
+{% for entry in shelf %}
+    {{ entry.title }}      {# `entry` is one element of `shelf` #}
+{% endfor %}
+
+{% with writer=book.author %}
+    {{ writer.name }}      {# `writer` is `book.author` #}
+{% endwith %}
+```
+
+these are the places a context is read from:
+
+- `render(request, "…", {…})` and `TemplateResponse(request, "…", {…})`, positionally or by keyword
+- a class-based view's `template_name`, together with its `context_object_name`, its `extra_context`, and the `context["…"] = …` writes in its `get_context_data`
+
+two views rendering the same template both contribute; a name they agree on appears once.
+
+## how a template is recognised
+
+the editor usually says so: `django-html`, `htmldjango`, `django-txt` and `jinja-html` are all taken as django templates.
+
+when the editor just calls the file `html` — which is what plain vs code does — the path decides: a file with a template-ish extension (`.html`, `.htm`, `.txt`, `.xml`, `.django`, `.jinja`) somewhere under a directory named `templates` is a django template. ordinary html elsewhere in the project is left alone.
+
+template directories, static directories and tag libraries are found by their conventional names, which is what django's own app-directories loaders use:
+
+- `**/templates/**` — templates, named by their path below `templates/`
+- `**/static/**` — static files, named by their path below `static/`
+- `**/templatetags/*.py` — tag libraries, named by their module
+
+## limitations
+
+**no diagnostics.** templates are never type-checked. an unknown variable or a misspelled filter is not reported — it just doesn't complete.
+
+**a `TEMPLATES` setting is not read.** template directories are found by name rather than from `settings.py`, so a `DIRS` entry pointing somewhere else is not picked up.
+
+**dictionary lookups don't resolve.** django tries a subscript before an attribute, so `{{ mapping.key }}` works at runtime, but a mapping's keys are values rather than types and completions can only offer attributes.
+
+**callables are not called.** django calls `{{ author.get_full_name }}` for you; the server reports the method's type rather than its return type, so attributes past a call don't resolve.
+
+**`{% url %}` namespaces come from `app_name`.** a namespace given at the `include()` instead is not applied.
+
+## see also
+
+- [django support](django.md) — the type checker's understanding of models, fields and queries
+- [django template language](https://docs.djangoproject.com/en/stable/ref/templates/language/)
+- [django template partials](https://docs.djangoproject.com/en/stable/ref/templates/builtins/#partialdef)
diff --git a/docs/basedpython/frameworks/django.md b/docs/basedpython/frameworks/django.md
index d946c79931..9e359ac105 100644
--- a/docs/basedpython/frameworks/django.md
+++ b/docs/basedpython/frameworks/django.md
@@ -138,8 +138,13 @@ def get_author_email(book_id: int) -> str | None:
     return book.author?.email  # checks correctly
 ```
 
+## templates
+
+django template files get their own language support in the editor — completions, go-to-definition and semantic highlighting, all joined up with the models, views and urls described here. see [django templates](django-templates.md).
+
 ## see also
 
+- [django templates](django-templates.md) — editor support for template files
 - [django documentation](https://docs.djangoproject.com/)
 - [django-stubs](https://github.com/typeddjango/django-stubs)
 - framework compatibility matrix in the [frameworks overview](index.md#basedpython-features-and-framework-compatibility)
diff --git a/zensical.toml b/zensical.toml
index c8b510daef..0253712605 100644
--- a/zensical.toml
+++ b/zensical.toml
@@ -197,6 +197,7 @@ features = [
   { "SQLAlchemy" = "frameworks/sqlalchemy.md" },
   { "pytest" = "frameworks/pytest.md" },
   { "Django" = "frameworks/django.md" },
+  { "Django templates" = "frameworks/django-templates.md" },
 ]
 
 [[project.nav]]

From 248d89160f53a1fc7952016293a9dab0703162e5 Mon Sep 17 00:00:00 2001
From: KotlinIsland <65446343+kotlinisland@users.noreply.github.com>
Date: Sat, 8 Aug 2026 21:38:32 +1000
Subject: [PATCH 02/16] address the django template review, and fixes
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

a construct is bounded to its own line, the way django's own tag_re is, so a
stray `{%` no longer swallows the rest of the file. the filesystem walks gained a
salsa revision, so a template added on disk is seen. a member that is callable
with no required arguments contributes its return type, because that is django's
documented resolution and `.all` is in most real templates

and django 6.0 ships the partial tags itself, so marking them third-party was
wrong — it would have written a `{% load partials %}` that raises
---
 crates/ty_ide/src/django_template.rs          |  37 +++
 crates/ty_ide/src/django_template/builtins.rs |  23 +-
 .../ty_ide/src/django_template/completion.rs  | 213 +++++++++----
 crates/ty_ide/src/django_template/goto.rs     |  98 +++---
 crates/ty_ide/src/django_template/index.rs    |  71 ++---
 crates/ty_ide/src/django_template/lexer.rs    | 189 ++++++++++--
 crates/ty_ide/src/django_template/project.rs  | 290 +++++++++++++++++-
 crates/ty_ide/src/django_template/resolve.rs  |  41 ++-
 .../src/django_template/semantic_tokens.rs    |  32 +-
 crates/ty_project/src/db/changes.rs           |  17 +
 crates/ty_project/src/lib.rs                  |  12 +
 .../src/types/ide_support.rs                  |  34 ++
 crates/ty_server/src/capabilities.rs          |   5 +-
 .../src/server/api/requests/completion.rs     |  26 ++
 .../server/api/requests/semantic_tokens.rs    |   3 +-
 .../ty_server/tests/e2e/django_templates.rs   |  37 ++-
 crates/ty_server/tests/e2e/main.rs            |   1 -
 .../frameworks/django-templates.md            |  27 +-
 18 files changed, 921 insertions(+), 235 deletions(-)

diff --git a/crates/ty_ide/src/django_template.rs b/crates/ty_ide/src/django_template.rs
index 8f20052d06..0033e98062 100644
--- a/crates/ty_ide/src/django_template.rs
+++ b/crates/ty_ide/src/django_template.rs
@@ -31,6 +31,9 @@ use crate::{NavigationTargets, RangedValue};
 
 use index::TemplateIndex;
 
+/// how many `{% extends %}` hops a parent chain is followed
+const MAX_INHERITANCE_DEPTH: usize = 16;
+
 /// the file extensions a django template is conventionally written with
 ///
 /// django itself puts no constraint on the extension — the template loader takes
@@ -97,6 +100,40 @@ pub fn django_template_goto_definition(
     goto::goto_definition(db, file, template_index(db, file), source.as_str(), offset)
 }
 
+/// the templates `index` extends, nearest ancestor first
+///
+/// a template whose parent chain has a cycle in it would not render, but the
+/// editor must not hang on one, so the walk stops at the first template it has
+/// already been through — and at [`MAX_INHERITANCE_DEPTH`] regardless.
+fn ancestors<'db>(
+    db: &'db dyn Db,
+    file: File,
+    index: &TemplateIndex,
+) -> Vec<(File, &'db TemplateIndex)> {
+    let mut collected = Vec::new();
+    let mut seen = vec![file];
+    let mut parent = index.extends().map(|reference| reference.name.clone());
+
+    while collected.len() < MAX_INHERITANCE_DEPTH {
+        let Some(name) = parent.take() else { break };
+        let Some(parent_file) = project::resolve_template(db, &name) else {
+            break;
+        };
+        if seen.contains(&parent_file) {
+            break;
+        }
+        seen.push(parent_file);
+
+        let parent_index = template_index(db, parent_file);
+        collected.push((parent_file, parent_index));
+        parent = parent_index
+            .extends()
+            .map(|reference| reference.name.clone());
+    }
+
+    collected
+}
+
 /// the completions for `offset` in `file`, read as a django template
 pub fn django_template_completions(
     db: &dyn Db,
diff --git a/crates/ty_ide/src/django_template/builtins.rs b/crates/ty_ide/src/django_template/builtins.rs
index 0bee7ac9f8..632a771cd6 100644
--- a/crates/ty_ide/src/django_template/builtins.rs
+++ b/crates/ty_ide/src/django_template/builtins.rs
@@ -50,6 +50,9 @@ pub(crate) fn end_tag_for(name: &str) -> Option<&'static str> {
 }
 
 /// the libraries a `{% load %}` can name
+///
+/// every one of them ships with django. a tag or filter the project registers is
+/// discovered from its source instead, and named by its module.
 pub(crate) const LIBRARIES: &[&str] = &["cache", "i18n", "l10n", "static", "tz"];
 
 pub(crate) const TAGS: &[Tag] = &[
@@ -708,7 +711,7 @@ pub(crate) const FILTERS: &[Filter] = &[
 
 #[cfg(test)]
 mod tests {
-    use super::{FILTERS, TAGS, end_tag_for, filter, tag};
+    use super::{FILTERS, LIBRARIES, TAGS, end_tag_for, filter, tag};
 
     #[test]
     fn tag_names_are_unique() {
@@ -752,6 +755,21 @@ mod tests {
         }
     }
 
+    #[test]
+    fn every_library_a_tag_or_filter_names_is_listed() {
+        let libraries = TAGS
+            .iter()
+            .filter_map(|tag| tag.library)
+            .chain(FILTERS.iter().filter_map(|filter| filter.library));
+
+        for library in libraries {
+            assert!(
+                LIBRARIES.contains(&library),
+                "`{library}` is never offered to a `{{% load %}}`"
+            );
+        }
+    }
+
     #[test]
     fn lookup() {
         assert_eq!(end_tag_for("for"), Some("endfor"));
@@ -765,5 +783,8 @@ mod tests {
         assert_eq!(tag("partial").and_then(|tag| tag.closed_by), None);
         assert_eq!(filter("upper").map(|filter| filter.library), Some(None));
         assert_eq!(tag("static").map(|tag| tag.library), Some(Some("static")));
+        // django 6.0 ships the partial tags; before that they came from
+        // django-template-partials and needed `{% load partials %}`
+        assert_eq!(tag("partialdef").map(|tag| tag.library), Some(None));
     }
 }
diff --git a/crates/ty_ide/src/django_template/completion.rs b/crates/ty_ide/src/django_template/completion.rs
index 623ba4b86b..331860d0e4 100644
--- a/crates/ty_ide/src/django_template/completion.rs
+++ b/crates/ty_ide/src/django_template/completion.rs
@@ -22,13 +22,10 @@ use crate::completion::CompletionKind;
 
 use super::builtins;
 use super::index::{Block, TemplateIndex};
-use super::lexer::{Construct, ConstructKind, Token, TokenKind};
+use super::lexer::{Construct, ConstructKind, Token, TokenKind, string_contents};
 use super::project::{self, RegistrationKind};
 use super::resolve;
 
-/// how many `{% extends %}` hops the parent chain is followed
-const MAX_INHERITANCE_DEPTH: u32 = 16;
-
 /// an edit a completion carries alongside the text it inserts
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct TemplateEdit {
@@ -109,8 +106,8 @@ pub(crate) fn completions(
         Context::StaticPath => static_paths(db, &cursor),
         Context::UrlName => url_names(db, &cursor),
         Context::Library => libraries(db, index, &cursor),
-        Context::BlockName => block_names(db, index, &cursor),
-        Context::PartialName => partial_names(db, index, &cursor),
+        Context::BlockName => block_names(db, file, index, &cursor),
+        Context::PartialName => partial_names(db, file, index, &cursor),
     }
 }
 
@@ -161,16 +158,7 @@ impl<'a> Cursor<'a> {
         construct: &'a Construct,
         offset: TextSize,
     ) -> Self {
-        let all = index.lexed().construct_tokens(construct);
-        let start = usize::from(
-            all.first()
-                .is_some_and(|token| token.kind == TokenKind::Delimiter),
-        );
-        let end = all
-            .iter()
-            .rposition(|token| token.kind != TokenKind::Delimiter)
-            .map_or(start, |index| index + 1);
-        let tokens = all.get(start..end.max(start)).unwrap_or_default();
+        let tokens = index.lexed().inner_tokens(construct);
 
         // only a token the user could still be *typing* counts as the one under
         // the cursor. a cursor at the end of a `.` or a `|` is not editing that
@@ -202,6 +190,17 @@ impl<'a> Cursor<'a> {
         self.construct.name.map_or("", |range| &self.source[range])
     }
 
+    /// whether the cursor is inside a string literal
+    ///
+    /// the argument naming a template, a route or an asset has to be quoted, so
+    /// a suggestion offered where there is no literal yet has to bring the quotes
+    /// along with it.
+    fn in_string(&self) -> bool {
+        self.current
+            .and_then(|index| self.tokens.get(index))
+            .is_some_and(|token| token.kind == TokenKind::String)
+    }
+
     /// the token before the cursor, skipping the one being typed
     fn previous(&self) -> Option<&'a Token> {
         let before = match self.current {
@@ -337,24 +336,14 @@ fn is_word(kind: TokenKind) -> bool {
     )
 }
 
-/// the contents of a string literal, its quotes excluded
-fn string_contents(source: &str, range: TextRange) -> TextRange {
-    let text = &source[range];
-    let Some(quote) = text.chars().next() else {
-        return range;
-    };
-    if !matches!(quote, '"' | '\'') {
-        return range;
-    }
-
-    let start = range.start() + TextSize::from(1);
-    let end = if text.len() > 1 && text.ends_with(quote) {
-        range.end() - TextSize::from(1)
-    } else {
-        range.end()
-    };
-
-    TextRange::new(start, end.max(start))
+/// the text a suggestion for a quoted argument inserts, when it differs from
+/// the label
+///
+/// `{% extends '<CURSOR>' %}` needs the name alone; `{% extends <CURSOR> %}`
+/// needs it quoted, or accepting the suggestion writes something django reads as
+/// a variable.
+fn quoted_insert(label: &str, cursor: &Cursor<'_>) -> Option<String> {
+    (!cursor.in_string()).then(|| format!("'{label}'"))
 }
 
 fn tag_names(
@@ -566,8 +555,11 @@ fn discovered(files: &[project::DiscoveredFile], cursor: &Cursor<'_>) -> Vec<Tem
         .iter()
         .filter(|file| seen.insert(file.name.clone()))
         .map(|file| {
-            TemplateCompletion::new(file.name.as_str(), CompletionKind::File, cursor.range)
-                .detail(file.path.as_str())
+            let mut completion =
+                TemplateCompletion::new(file.name.as_str(), CompletionKind::File, cursor.range)
+                    .detail(file.path.as_str());
+            completion.insert = quoted_insert(&file.name, cursor);
+            completion
         })
         .collect()
 }
@@ -579,6 +571,7 @@ fn url_names(db: &dyn Db, cursor: &Cursor<'_>) -> Vec<TemplateCompletion> {
             let mut completion =
                 TemplateCompletion::new(url.name.as_str(), CompletionKind::Reference, cursor.range);
             completion.detail = url.route.as_deref().map(ToString::to_string);
+            completion.insert = quoted_insert(&url.name, cursor);
             completion
         })
         .collect()
@@ -617,7 +610,12 @@ fn libraries(db: &dyn Db, index: &TemplateIndex, cursor: &Cursor<'_>) -> Vec<Tem
     completions
 }
 
-fn block_names(db: &dyn Db, index: &TemplateIndex, cursor: &Cursor<'_>) -> Vec<TemplateCompletion> {
+fn block_names(
+    db: &dyn Db,
+    file: File,
+    index: &TemplateIndex,
+    cursor: &Cursor<'_>,
+) -> Vec<TemplateCompletion> {
     // a `{% block %}` in a child template is only useful when it overrides one of
     // the parent's, so those are exactly what is offered
     let defined: FxHashSet<_> = index
@@ -626,7 +624,7 @@ fn block_names(db: &dyn Db, index: &TemplateIndex, cursor: &Cursor<'_>) -> Vec<T
         .map(|block| block.name.clone())
         .collect();
 
-    inherited(db, index, |parent| {
+    inherited(db, file, index, |parent| {
         parent
             .blocks()
             .iter()
@@ -644,6 +642,7 @@ fn block_names(db: &dyn Db, index: &TemplateIndex, cursor: &Cursor<'_>) -> Vec<T
 
 fn partial_names(
     db: &dyn Db,
+    file: File,
     index: &TemplateIndex,
     cursor: &Cursor<'_>,
 ) -> Vec<TemplateCompletion> {
@@ -654,7 +653,7 @@ fn partial_names(
         .collect();
 
     // a partial defined by a template this one extends is in scope here too
-    names.extend(inherited(db, index, |parent| {
+    names.extend(inherited(db, file, index, |parent| {
         parent
             .partials()
             .iter()
@@ -676,32 +675,14 @@ fn partial_names(
 /// collect `names` from every template up the `{% extends %}` chain
 fn inherited(
     db: &dyn Db,
+    file: File,
     index: &TemplateIndex,
     names: impl Fn(&TemplateIndex) -> Vec<CompactString>,
 ) -> Vec<CompactString> {
-    let mut collected = Vec::new();
-    let mut seen = FxHashSet::default();
-    let mut parent = index.extends().map(|reference| reference.name.clone());
-
-    for _ in 0..MAX_INHERITANCE_DEPTH {
-        let Some(name) = parent.take() else { break };
-        let Some(file) = project::resolve_template(db, &name) else {
-            break;
-        };
-        if !seen.insert(file) {
-            // a cycle in the inheritance chain; django would fail to render it,
-            // but the editor must not hang on it
-            break;
-        }
-
-        let parent_index = super::template_index(db, file);
-        collected.extend(names(parent_index));
-        parent = parent_index
-            .extends()
-            .map(|reference| reference.name.clone());
-    }
-
-    collected
+    super::ancestors(db, file, index)
+        .into_iter()
+        .flat_map(|(_, parent)| names(parent))
+        .collect()
 }
 
 /// the libraries the template has already `{% load %}`ed
@@ -765,16 +746,32 @@ mod tests {
                 class Book:
                     title: str
                     author: Author
+
+                class Chapter:
+                    title: str
+                    number: int
+
+                # stands in for `models.Model`: a framework base that brings a
+                # pile of machinery with it
+                class Model:
+                    def save(self) -> None: ...
+                    def delete(self) -> None: ...
+
+                class Novel(Model):
+                    title: str
+
+                    def chapters(self) -> list[Chapter]: ...
+                    def rename(self, title: str) -> str: ...
                 ",
             ),
             (
                 "blog/views.py",
                 "
-                from blog.models import Book
+                from blog.models import Book, Novel
 
                 def post(request):
                     book = Book()
-                    return render(request, 'blog/post.html', {'book': book, 'shelf': [book]})
+                    return render(request, 'blog/post.html', {'book': book, 'shelf': [book], 'novel': Novel()})
                 ",
             ),
             (
@@ -980,6 +977,37 @@ mod tests {
         assert_eq!(&source[usize::from(range.start())..], "blog/<CURSOR>' %}");
     }
 
+    #[test]
+    fn a_template_path_offered_outside_a_literal_brings_its_quotes() {
+        let test = project("{% extends <CURSOR> %}");
+        let completions = django_template_completions(&test.db, test.file, test.offset);
+
+        let first = completions.first().expect("a template to be offered");
+        assert_eq!(first.label, "blog/base.html");
+        assert_eq!(
+            first.insert.as_deref(),
+            Some("'blog/base.html'"),
+            "an unquoted path would be read as a variable"
+        );
+    }
+
+    #[test]
+    fn a_template_path_offered_inside_a_literal_does_not() {
+        let test = project("{% extends '<CURSOR>' %}");
+        let completions = django_template_completions(&test.db, test.file, test.offset);
+
+        assert_eq!(completions[0].insert, None);
+    }
+
+    #[test]
+    fn a_url_name_offered_outside_a_literal_brings_its_quotes() {
+        let test = project("{% url <CURSOR> %}");
+        let completions = django_template_completions(&test.db, test.file, test.offset);
+
+        let first = completions.first().expect("a route to be offered");
+        assert_eq!(first.insert.as_deref(), Some("'blog:detail'"));
+    }
+
     #[test]
     fn url_offers_the_projects_route_names_namespaced() {
         let completions = project("{% url '<CURSOR>' %}").detailed();
@@ -1012,14 +1040,14 @@ mod tests {
     #[test]
     fn a_bare_name_offers_the_views_context() {
         let completions = project("{{ <CURSOR> }}").completions();
-        assert_eq!(completions, ["book", "shelf"]);
+        assert_eq!(completions, ["book", "shelf", "novel"]);
     }
 
     #[test]
     fn a_bare_name_offers_the_templates_own_bindings_first() {
         let completions =
             project("{% for book in shelf %}{{ <CURSOR> }}{% endfor %}").completions();
-        assert_eq!(completions, ["book", "forloop", "shelf"]);
+        assert_eq!(completions, ["book", "forloop", "shelf", "novel"]);
     }
 
     #[test]
@@ -1054,6 +1082,59 @@ mod tests {
         assert_eq!(completions, ["email — str", "name — str"]);
     }
 
+    #[test]
+    fn a_no_argument_method_is_called_the_way_django_calls_it() {
+        // django's variable lookup calls whatever it lands on, so `book.chapters`
+        // is the list the method returns, not the method
+        let completions = project("{{ novel.chapters.<CURSOR> }}").completions();
+        assert!(
+            completions.contains(&"append".to_string()),
+            "got {completions:?}"
+        );
+    }
+
+    #[test]
+    fn a_loop_over_a_called_method_binds_the_element_type() {
+        let completions =
+            project("{% for c in novel.chapters %}{{ c.<CURSOR> }}{% endfor %}").detailed();
+        assert_eq!(completions, ["number — int", "title — str"]);
+    }
+
+    #[test]
+    fn a_method_that_needs_an_argument_is_not_called() {
+        // `book.rename(title)` takes an argument, so django would render nothing
+        // rather than call it, and there is no return type to offer
+        assert!(
+            project("{{ novel.rename.<CURSOR> }}")
+                .completions()
+                .is_empty()
+        );
+    }
+
+    #[test]
+    fn a_types_own_members_come_before_the_ones_it_inherits() {
+        // the base stands in for `models.Model`: what a template is written
+        // against is the subclass' own fields, and burying them alphabetically
+        // among a framework's machinery is nearly the same as not offering them
+        let completions = project("{{ novel.<CURSOR> }}").completions();
+        let own = ["chapters", "rename", "title"];
+
+        let last_own = own
+            .iter()
+            .map(|name| completions.iter().position(|c| c == name).expect(name))
+            .max()
+            .unwrap();
+        let first_inherited = completions
+            .iter()
+            .position(|c| c == "save")
+            .expect("the inherited member to be offered too");
+
+        assert!(
+            last_own < first_inherited,
+            "own members must lead: {completions:?}"
+        );
+    }
+
     #[test]
     fn an_unresolvable_path_offers_nothing_rather_than_guessing() {
         assert!(project("{{ mystery.<CURSOR> }}").completions().is_empty());
diff --git a/crates/ty_ide/src/django_template/goto.rs b/crates/ty_ide/src/django_template/goto.rs
index 4c57cd1eec..3e26bd9728 100644
--- a/crates/ty_ide/src/django_template/goto.rs
+++ b/crates/ty_ide/src/django_template/goto.rs
@@ -13,13 +13,10 @@ use ty_project::Db;
 use crate::{HasNavigationTargets, NavigationTarget, NavigationTargets, RangedValue};
 
 use super::index::TemplateIndex;
-use super::lexer::{ConstructKind, Token, TokenKind};
+use super::lexer::{ConstructKind, Token, TokenKind, string_contents};
 use super::project::{self, RegistrationKind};
 use super::resolve::{self, Origin};
 
-/// how many `{% extends %}` hops a partial or block is looked for through
-const MAX_INHERITANCE_DEPTH: u32 = 16;
-
 /// where the name at `offset` of the template `file` is defined
 pub(crate) fn goto_definition(
     db: &dyn Db,
@@ -131,12 +128,14 @@ impl Site<'_> {
 
                 let target = project::resolve_template(db, &reference.name)?;
                 let range = match &reference.partial {
-                    // `blog.html#comment-item` addresses one fragment of it
+                    // `blog.html#comment-item` addresses one fragment of it. a
+                    // fragment that isn't there is no reason to refuse to open
+                    // the template — that is where the user is going to look
                     Some(partial) => super::template_index(db, target)
                         .partials()
                         .iter()
                         .find(|candidate| candidate.name == *partial)
-                        .map(|candidate| candidate.name_range)?,
+                        .map_or_else(TextRange::default, |candidate| candidate.name_range),
                     None => TextRange::default(),
                 };
 
@@ -222,37 +221,21 @@ fn definition_in_chain(
     skip_current: bool,
     definitions: impl Fn(&TemplateIndex) -> &[super::index::Definition],
 ) -> Option<NavigationTargets> {
-    let mut current = (file, index);
-    let mut searchable = !skip_current;
-    let mut seen = vec![file];
-
-    for _ in 0..MAX_INHERITANCE_DEPTH {
-        let (file, index) = current;
+    let current = (!skip_current).then_some((file, index));
 
-        if searchable
-            && let Some(definition) = definitions(index)
+    current
+        .into_iter()
+        .chain(super::ancestors(db, file, index))
+        .find_map(|(file, index)| {
+            let definition = definitions(index)
                 .iter()
-                .find(|definition| definition.name == name)
-        {
-            return Some(NavigationTargets::from_iter([NavigationTarget::new(
+                .find(|definition| definition.name == name)?;
+
+            Some(NavigationTargets::from_iter([NavigationTarget::new(
                 file,
                 definition.name_range,
-            )]));
-        }
-
-        let parent = index.extends()?;
-        let parent_file = project::resolve_template(db, &parent.name)?;
-        if seen.contains(&parent_file) {
-            // an inheritance cycle would loop forever
-            return None;
-        }
-
-        seen.push(parent_file);
-        current = (parent_file, super::template_index(db, parent_file));
-        searchable = true;
-    }
-
-    None
+            )]))
+        })
 }
 
 /// the path segments up to and including `token`
@@ -302,26 +285,6 @@ fn path_up_to<'src>(
         .collect()
 }
 
-/// the contents of a string literal, its quotes excluded
-fn string_contents(source: &str, range: TextRange) -> TextRange {
-    let text = &source[range];
-    let Some(quote) = text.chars().next() else {
-        return range;
-    };
-    if !matches!(quote, '"' | '\'') {
-        return range;
-    }
-
-    let start = range.start() + TextSize::from(1);
-    let end = if text.len() > 1 && text.ends_with(quote) {
-        range.end() - TextSize::from(1)
-    } else {
-        range.end()
-    };
-
-    TextRange::new(start, end.max(start))
-}
-
 #[cfg(test)]
 mod tests {
     use crate::django_template::tests::TemplateTest;
@@ -409,6 +372,35 @@ mod tests {
         assert_eq!(test.definitions(), ["/blog/templates/blog/cards.html:card"]);
     }
 
+    #[test]
+    fn an_include_whose_fragment_is_missing_still_opens_the_template() {
+        let test = TemplateTest::new(&[
+            (
+                "blog/templates/blog/cards.html",
+                "{% block a %}{% endblock %}",
+            ),
+            (
+                "blog/templates/blog/post.html",
+                "{% include 'blog/car<CURSOR>ds.html#gone' %}",
+            ),
+        ]);
+
+        assert_eq!(test.definitions(), ["/blog/templates/blog/cards.html:"]);
+    }
+
+    #[test]
+    fn an_inheritance_cycle_does_not_hang() {
+        let test = TemplateTest::new(&[
+            (
+                "blog/templates/a.html",
+                "{% extends 'b.html' %}{% block x<CURSOR> %}",
+            ),
+            ("blog/templates/b.html", "{% extends 'a.html' %}"),
+        ]);
+
+        assert!(test.definitions().is_empty());
+    }
+
     #[test]
     fn url_navigates_to_the_route_that_is_named() {
         let definitions = project("{% url 'blog:<CURSOR>index' %}").definitions();
diff --git a/crates/ty_ide/src/django_template/index.rs b/crates/ty_ide/src/django_template/index.rs
index 5e8bff9c47..730565ebcc 100644
--- a/crates/ty_ide/src/django_template/index.rs
+++ b/crates/ty_ide/src/django_template/index.rs
@@ -15,7 +15,7 @@ use compact_str::{CompactString, ToCompactString};
 use ruff_text_size::{TextRange, TextSize};
 
 use super::builtins;
-use super::lexer::{Construct, ConstructKind, Lexed, Token, TokenKind, lex};
+use super::lexer::{Construct, ConstructKind, Lexed, Token, TokenKind, lex, string_contents};
 
 /// a name a template defines: a `{% block %}` or a `{% partialdef %}`
 #[derive(Debug, Clone, PartialEq, Eq, get_size2::GetSize)]
@@ -92,16 +92,20 @@ pub(crate) struct Block {
 }
 
 /// a template, lexed and indexed
+///
+/// every collection is boxed: the index is a salsa-cached value, and a `Vec`
+/// built by pushing would hold on to as much as half again its length in spare
+/// capacity for as long as the file stays open.
 #[derive(Debug, PartialEq, Eq, get_size2::GetSize)]
 pub(crate) struct TemplateIndex {
     lexed: Lexed,
     extends: Option<TemplateReference>,
-    includes: Vec<TemplateReference>,
-    blocks: Vec<Definition>,
-    partials: Vec<Definition>,
-    loads: Vec<Load>,
-    bindings: Vec<Binding>,
-    spans: Vec<Block>,
+    includes: Box<[TemplateReference]>,
+    blocks: Box<[Definition]>,
+    partials: Box<[Definition]>,
+    loads: Box<[Load]>,
+    bindings: Box<[Binding]>,
+    spans: Box<[Block]>,
 }
 
 impl TemplateIndex {
@@ -303,12 +307,12 @@ impl<'src> Builder<'src> {
         TemplateIndex {
             lexed: self.lexed,
             extends,
-            includes,
-            blocks,
-            partials,
-            loads,
-            bindings,
-            spans,
+            includes: includes.into_boxed_slice(),
+            blocks: blocks.into_boxed_slice(),
+            partials: partials.into_boxed_slice(),
+            loads: loads.into_boxed_slice(),
+            bindings: bindings.into_boxed_slice(),
+            spans: spans.into_boxed_slice(),
         }
     }
 
@@ -329,24 +333,13 @@ impl<'src> Builder<'src> {
 
     /// a construct's tokens with its delimiters and its tag name dropped
     fn arguments(&self, construct: &Construct) -> &[Token] {
-        let tokens = self.lexed.construct_tokens(construct);
+        let tokens = self.lexed.inner_tokens(construct);
 
-        let start = match tokens
-            .iter()
-            .position(|token| token.kind == TokenKind::TagName)
-        {
-            Some(index) => index + 1,
-            None => tokens
-                .iter()
-                .position(|token| token.kind != TokenKind::Delimiter)
-                .unwrap_or(tokens.len()),
-        };
-        let end = tokens
-            .iter()
-            .rposition(|token| token.kind != TokenKind::Delimiter)
-            .map_or(start, |index| index + 1);
-
-        tokens.get(start..end.max(start)).unwrap_or_default()
+        // the tag name is always the first token inside the delimiters
+        match tokens.split_first() {
+            Some((first, rest)) if first.kind == TokenKind::TagName => rest,
+            _ => tokens,
+        }
     }
 
     /// the block or partial `construct` defines
@@ -545,22 +538,8 @@ impl<'src> Builder<'src> {
             return None;
         }
 
-        let text = &self.source[token.range];
-        let quote = text.chars().next()?;
-        if !matches!(quote, '"' | '\'') {
-            return None;
-        }
-
-        let start = token.range.start() + TextSize::from(1);
-        // an unterminated literal still names a template: the user is mid-typing
-        let end = if text.len() > 1 && text.ends_with(quote) {
-            token.range.end() - TextSize::from(1)
-        } else {
-            token.range.end()
-        };
-
-        let range = TextRange::new(start, end.max(start));
-        Some((&self.source[range], range))
+        let range = string_contents(self.source, token.range);
+        (range != token.range).then(|| (&self.source[range], range))
     }
 }
 
diff --git a/crates/ty_ide/src/django_template/lexer.rs b/crates/ty_ide/src/django_template/lexer.rs
index 7ab6773aaf..1d4fe0c6b1 100644
--- a/crates/ty_ide/src/django_template/lexer.rs
+++ b/crates/ty_ide/src/django_template/lexer.rs
@@ -8,9 +8,9 @@
 //!
 //! the lexer is written for an editor rather than for a renderer, so it is
 //! deliberately tolerant: a construct whose closing delimiter the user has not
-//! typed yet still lexes, so that completions fire inside it. to keep the damage
-//! from a stray `{%` local, an unterminated construct ends at the end of its line
-//! rather than swallowing the rest of the file.
+//! typed yet still lexes, so that completions fire inside it. no construct ever
+//! crosses a newline — django's own lexer can't either — which is what keeps the
+//! damage from a stray `{%` to the line it is on.
 
 use std::ops::Range;
 
@@ -96,8 +96,8 @@ impl Construct {
 /// the result of lexing a whole template
 #[derive(Debug, Default, PartialEq, Eq, get_size2::GetSize)]
 pub(crate) struct Lexed {
-    tokens: Vec<Token>,
-    constructs: Vec<Construct>,
+    tokens: Box<[Token]>,
+    constructs: Box<[Construct]>,
 }
 
 impl Lexed {
@@ -114,21 +114,70 @@ impl Lexed {
         &self.tokens[construct.tokens.clone()]
     }
 
+    /// `construct`'s tokens with its opening and closing delimiters dropped
+    pub(crate) fn inner_tokens(&self, construct: &Construct) -> &[Token] {
+        let tokens = self.construct_tokens(construct);
+
+        let start = usize::from(
+            tokens
+                .first()
+                .is_some_and(|token| token.kind == TokenKind::Delimiter),
+        );
+        let end = tokens
+            .iter()
+            .rposition(|token| token.kind != TokenKind::Delimiter)
+            .map_or(start, |index| index + 1);
+
+        tokens.get(start..end.max(start)).unwrap_or_default()
+    }
+
     /// the construct `offset` sits in
     ///
-    /// the end of a construct counts as inside it: a cursor written as
-    /// `{% extends <CURSOR>%}` is at the boundary of the space token, and a
-    /// cursor at the very end of an unterminated `{% extends ` is at the
-    /// boundary of the construct itself.
+    /// a cursor at the very end of an *unterminated* construct is inside it: the
+    /// user is still typing `{% extends `. a cursor at the end of a terminated
+    /// one is past its closing delimiter and so back in the markup, which is why
+    /// `{{ book }}<CURSOR>` offers nothing.
     pub(crate) fn construct_at(&self, offset: TextSize) -> Option<&Construct> {
-        let index = self
+        let mut index = self
             .constructs
             .partition_point(|construct| construct.range.end() < offset);
+
+        if self
+            .constructs
+            .get(index)
+            .is_some_and(|construct| construct.terminated && construct.range.end() == offset)
+        {
+            index += 1;
+        }
+
         let construct = self.constructs.get(index)?;
         (construct.range.start() <= offset).then_some(construct)
     }
 }
 
+/// the contents of a string literal, its quotes excluded
+///
+/// a literal whose closing quote the user has not typed yet keeps everything
+/// after the opening one, so that it still names whatever it is naming.
+pub(crate) fn string_contents(source: &str, range: TextRange) -> TextRange {
+    let text = &source[range];
+    let Some(quote) = text.chars().next() else {
+        return range;
+    };
+    if !matches!(quote, '"' | '\'') {
+        return range;
+    }
+
+    let start = range.start() + TextSize::from(1);
+    let end = if text.len() > 1 && text.ends_with(quote) {
+        range.end() - TextSize::from(1)
+    } else {
+        range.end()
+    };
+
+    TextRange::new(start, end.max(start))
+}
+
 /// lex `source` as a django template
 pub(crate) fn lex(source: &str) -> Lexed {
     Lexer::new(source).lex()
@@ -192,8 +241,8 @@ impl<'src> Lexer<'src> {
         }
 
         Lexed {
-            tokens: self.tokens,
-            constructs: self.constructs,
+            tokens: self.tokens.into_boxed_slice(),
+            constructs: self.constructs.into_boxed_slice(),
         }
     }
 
@@ -254,28 +303,32 @@ impl<'src> Lexer<'src> {
 
     /// the offset of `close` searching from the cursor, and whether it was found
     ///
-    /// an unterminated construct is cut off at the end of its line so that a
-    /// stray `{%` costs the user one line of highlighting rather than the whole
-    /// rest of the file.
+    /// the search never leaves the line. django's own lexer matches a construct
+    /// with a pattern that cannot cross a newline, so a construct that spans one
+    /// is not a construct — and searching on regardless would let a stray `{%`
+    /// swallow the next tag's `%}` and, with it, that tag.
     fn find_close(&self, close: &str) -> (usize, bool) {
-        let rest = &self.source[self.offset..];
-        match rest.find(close) {
+        let line_end = self.line_end();
+        match self.source[self.offset..line_end].find(close) {
             Some(index) => (self.offset + index, true),
-            None => {
-                let line_end = rest.find('\n').map_or(self.source.len(), |index| {
-                    let end = self.offset + index;
-                    // keep a `\r\n` terminator out of the construct
-                    if self.source[..end].ends_with('\r') {
-                        end - 1
-                    } else {
-                        end
-                    }
-                });
-                (line_end, false)
-            }
+            None => (line_end, false),
         }
     }
 
+    /// the end of the line the cursor is on, its terminator excluded
+    fn line_end(&self) -> usize {
+        let rest = &self.source[self.offset..];
+        rest.find('\n').map_or(self.source.len(), |index| {
+            let end = self.offset + index;
+            // keep a `\r\n` terminator out of the construct
+            if self.source[..end].ends_with('\r') {
+                end - 1
+            } else {
+                end
+            }
+        })
+    }
+
     /// lex the inside of a `{{ … }}` or `{% … %}`, up to `end`
     ///
     /// returns the range of the tag name when `expect_tag_name` is set and a name
@@ -800,6 +853,44 @@ mod tests {
         assert!(!lexed.constructs()[0].terminated);
     }
 
+    #[test]
+    fn an_unterminated_construct_does_not_reach_a_later_constructs_delimiter() {
+        // the `%}` below belongs to the `{% block %}`, and taking it would erase
+        // that tag from the template — which is what the user sees the moment
+        // they type `{%` on a line above one
+        let source = "{% extends 'base.html'\n<p>hi</p>\n{% block content %}{% endblock %}";
+        let lexed = lex(source);
+
+        assert_eq!(
+            constructs(&lexed, source),
+            [
+                "Tag(extends):{% extends 'base.html'",
+                "Tag(block):{% block content %}",
+                "Tag(endblock):{% endblock %}",
+            ]
+        );
+        assert!(!lexed.constructs()[0].terminated);
+    }
+
+    #[test]
+    fn a_construct_never_crosses_a_newline() {
+        // django's own lexer matches with a pattern that cannot cross one, so a
+        // `{{` and a `}}` on different lines are two runs of literal text
+        let source = "{{ book\n.title }}";
+        let lexed = lex(source);
+
+        assert_eq!(lexed.constructs().len(), 1);
+        assert!(!lexed.constructs()[0].terminated);
+        assert_eq!(&source[lexed.constructs()[0].range], "{{ book");
+    }
+
+    #[test]
+    fn a_carriage_return_is_not_part_of_an_unterminated_construct() {
+        let source = "{% extends\r\n<p>text</p>";
+        let lexed = lex(source);
+        assert_eq!(&source[lexed.constructs()[0].range], "{% extends");
+    }
+
     #[test]
     fn unterminated_raw_body_does_not_swallow_the_file() {
         // the closing tag is missing, so the body must keep lexing as template
@@ -847,10 +938,46 @@ mod tests {
 
         assert_eq!(at(0), None, "before any construct");
         assert_eq!(at(1), Some(String::new()), "the `{{` itself");
-        assert_eq!(at(8), Some(String::new()), "the end of `}}`");
+        assert_eq!(at(7), Some(String::new()), "inside the closing braces");
+        assert_eq!(at(8), None, "past the closing braces");
         assert_eq!(at(9), None, "the literal text between them");
         assert_eq!(at(14), Some("if".to_string()));
-        assert_eq!(at(20), Some("if".to_string()), "the closing delimiter");
+        assert_eq!(
+            at(19),
+            Some("if".to_string()),
+            "inside the closing delimiter"
+        );
+        assert_eq!(at(20), None, "past the closing delimiter");
+    }
+
+    #[test]
+    fn the_end_of_an_unterminated_construct_is_still_inside_it() {
+        // the user is mid-way through typing it, and this is where completions
+        // have to fire
+        let source = "{% extends ";
+        let lexed = lex(source);
+        let end = ruff_text_size::TextSize::try_from(source.len()).unwrap();
+
+        assert_eq!(
+            lexed
+                .construct_at(end)
+                .map(|construct| construct.name(source)),
+            Some("extends")
+        );
+    }
+
+    #[test]
+    fn adjacent_constructs_do_not_overlap_at_their_boundary() {
+        let source = "{{ a }}{{ b }}";
+        let lexed = lex(source);
+
+        let at = |offset: usize| {
+            lexed
+                .construct_at(ruff_text_size::TextSize::try_from(offset).unwrap())
+                .map(|construct| &source[construct.range])
+        };
+
+        assert_eq!(at(7), Some("{{ b }}"), "the second one, not the first");
     }
 
     #[test]
diff --git a/crates/ty_ide/src/django_template/project.rs b/crates/ty_ide/src/django_template/project.rs
index 217f6167f9..0645c61979 100644
--- a/crates/ty_ide/src/django_template/project.rs
+++ b/crates/ty_ide/src/django_template/project.rs
@@ -17,6 +17,7 @@ use std::sync::Mutex;
 use compact_str::{CompactString, ToCompactString};
 use ruff_db::files::{File, FilePath, system_path_to_file};
 use ruff_db::parsed::parsed_module;
+use ruff_db::source::source_text;
 use ruff_db::system::walk_directory::WalkState;
 use ruff_db::system::{FileType, SystemPath, SystemPathBuf};
 use ruff_python_ast::visitor::{Visitor, walk_expr, walk_stmt};
@@ -33,6 +34,18 @@ const STATIC_DIRECTORY: &str = "static";
 /// the package name a project's template tag libraries live in
 const TEMPLATETAGS_PACKAGE: &str = "templatetags";
 
+/// the functions that render a named template with a context
+const CONTEXT_CALLEES: &[&str] = &["render", "TemplateResponse"];
+
+/// the class attribute a generic view names its template with
+const TEMPLATE_NAME_ATTRIBUTE: &str = "template_name";
+
+/// the functions that give a route a reversible name
+const URL_CALLEES: &[&str] = &["path", "re_path", "url"];
+
+/// the keyword those functions take the name by
+const URL_NAME_KEYWORD: &str = "name";
+
 /// how deep below the project root a `templates`/`static` directory is looked for
 ///
 /// django's own layout puts them at `<project>/<app>/templates`, and a
@@ -209,6 +222,11 @@ where
 /// the walk is bounded (see [`DISCOVERY_DEPTH`]) and respects the project's
 /// ignore-file settings, so a repository's dependencies are not crawled.
 fn discover(db: &dyn Db, project: Project, directory: &str) -> Box<[DiscoveredFile]> {
+    // walking the file system is invisible to salsa, so the callers' queries would
+    // hand back their first answer forever. reading the revision the project bumps
+    // on every create and delete is what makes a template added mid-session show up
+    let _ = project.file_system_revision(db);
+
     let root = project.root(db);
     let found = Mutex::new(Vec::new());
 
@@ -440,9 +458,25 @@ fn registered_name(
     function.id.to_compact_string()
 }
 
+/// whether `file`'s source spells any of `names` somewhere
+///
+/// every name the scans below match is compared against an identifier that has
+/// to be written out in the source, so a file whose text doesn't contain it
+/// cannot produce a result and doesn't need parsing. skipping those is what
+/// keeps one template's completions from parsing a project's every file.
+fn mentions(db: &dyn Db, file: File, names: &[&str]) -> bool {
+    let source = source_text(db, file);
+    names.iter().any(|name| source.contains(name))
+}
+
 /// the url names one module defines
 #[salsa::tracked(returns(ref), heap_size=ruff_memory_usage::heap_size)]
 fn url_names_in_file(db: &dyn Db, file: File) -> Box<[UrlName]> {
+    // a named route is a `path()`-like call carrying a `name=` keyword
+    if !mentions(db, file, URL_CALLEES) || !mentions(db, file, &[URL_NAME_KEYWORD]) {
+        return Box::default();
+    }
+
     let parsed = parsed_module(db, file).load(db);
 
     // django namespaces an included module's names under its `app_name`
@@ -475,11 +509,8 @@ struct UrlVisitor {
 impl<'ast> Visitor<'ast> for UrlVisitor {
     fn visit_expr(&mut self, expr: &'ast Expr) {
         if let Expr::Call(call) = expr
-            && matches!(
-                callee_name(&call.func).as_deref(),
-                Some("path" | "re_path" | "url")
-            )
-            && let Some(keyword) = call.arguments.find_keyword("name")
+            && callee_name(&call.func).is_some_and(|callee| URL_CALLEES.contains(&callee.as_str()))
+            && let Some(keyword) = call.arguments.find_keyword(URL_NAME_KEYWORD)
             && let Some(name) = string_literal(&keyword.value)
         {
             let name = match &self.namespace {
@@ -507,6 +538,11 @@ impl<'ast> Visitor<'ast> for UrlVisitor {
 /// the template contexts one module builds
 #[salsa::tracked(returns(ref), heap_size=ruff_memory_usage::heap_size)]
 fn template_contexts_in_file(db: &dyn Db, file: File) -> Box<[TemplateContext]> {
+    // a context comes from a render call or from a view class naming its template
+    if !mentions(db, file, CONTEXT_CALLEES) && !mentions(db, file, &[TEMPLATE_NAME_ATTRIBUTE]) {
+        return Box::default();
+    }
+
     let parsed = parsed_module(db, file).load(db);
 
     let mut visitor = ContextVisitor {
@@ -530,14 +566,15 @@ impl ContextVisitor {
     /// and both accept those last two by keyword as well.
     fn render_call(&self, call: &ast::ExprCall) -> Option<TemplateContext> {
         let callee = callee_name(&call.func)?;
-        let (template_index, context_index) = match callee.as_str() {
-            "render" | "TemplateResponse" => (1, 2),
-            _ => return None,
-        };
+        if !CONTEXT_CALLEES.contains(&callee.as_str()) {
+            return None;
+        }
+        // both take the request first, the template second and the context third
+        let (template_index, context_index) = (1, 2);
 
         let template = call
             .arguments
-            .find_keyword("template_name")
+            .find_keyword(TEMPLATE_NAME_ATTRIBUTE)
             .map(|keyword| &keyword.value)
             .or_else(|| call.arguments.args.get(template_index))
             .and_then(string_literal)?;
@@ -585,7 +622,7 @@ impl ContextVisitor {
         let template = class
             .body
             .iter()
-            .find_map(|statement| class_attribute(statement, "template_name"))
+            .find_map(|statement| class_attribute(statement, TEMPLATE_NAME_ATTRIBUTE))
             .and_then(|(value, _)| string_literal(value))?;
 
         let mut variables = Vec::new();
@@ -738,3 +775,234 @@ fn docstring_summary(body: &[Stmt]) -> Option<Box<str>> {
 
     (!summary.is_empty()).then(|| Box::from(summary.as_str()))
 }
+
+#[cfg(test)]
+mod tests {
+    use ty_project::Db;
+
+    use crate::django_template::tests::TemplateTest;
+
+    use super::{RegistrationKind, context_for_template, registrations, url_names};
+
+    /// a project of python sources, with a throwaway template to anchor the
+    /// harness' cursor
+    fn project(sources: &[(&str, &str)]) -> TemplateTest {
+        let mut all = sources.to_vec();
+        all.push(("app/templates/app/page.html", "<CURSOR>"));
+        TemplateTest::new(&all)
+    }
+
+    /// the names a view puts in `template`'s context, in the order offered
+    fn context(test: &TemplateTest, template: &str) -> Vec<String> {
+        context_for_template(&test.db, template)
+            .into_iter()
+            .map(|variable| variable.name.to_string())
+            .collect()
+    }
+
+    #[test]
+    fn a_class_based_view_contributes_every_name_it_declares() {
+        let test = project(&[(
+            "app/views.py",
+            "
+            class BookDetail:
+                template_name = 'app/detail.html'
+                context_object_name = 'book'
+                extra_context = {'title': 'a book'}
+
+                def get_context_data(self, **kwargs):
+                    context = super().get_context_data(**kwargs)
+                    context['related'] = []
+                    return context
+            ",
+        )]);
+
+        assert_eq!(
+            context(&test, "app/detail.html"),
+            ["book", "title", "related"]
+        );
+    }
+
+    #[test]
+    fn a_class_based_view_without_a_template_name_names_no_template() {
+        let test = project(&[(
+            "app/views.py",
+            "
+            class Base:
+                context_object_name = 'book'
+            ",
+        )]);
+
+        assert!(context(&test, "app/detail.html").is_empty());
+    }
+
+    #[test]
+    fn a_template_response_builds_a_context_just_as_render_does() {
+        let test = project(&[(
+            "app/views.py",
+            "
+            def show(request):
+                return TemplateResponse(request, 'app/page.html', {'book': 1})
+            ",
+        )]);
+
+        assert_eq!(context(&test, "app/page.html"), ["book"]);
+    }
+
+    #[test]
+    fn a_render_call_may_pass_the_template_and_context_by_keyword() {
+        let test = project(&[(
+            "app/views.py",
+            "
+            def show(request):
+                return render(request, template_name='app/page.html', context={'book': 1})
+            ",
+        )]);
+
+        assert_eq!(context(&test, "app/page.html"), ["book"]);
+    }
+
+    #[test]
+    fn two_views_of_one_template_both_contribute_and_a_shared_name_appears_once() {
+        let test = project(&[(
+            "app/views.py",
+            "
+            def one(request):
+                return render(request, 'app/page.html', {'book': 1, 'shelf': 2})
+
+            def two(request):
+                return render(request, 'app/page.html', {'book': 3, 'author': 4})
+            ",
+        )]);
+
+        assert_eq!(context(&test, "app/page.html"), ["book", "shelf", "author"]);
+    }
+
+    #[test]
+    fn a_view_module_that_renders_nothing_is_not_parsed_for_contexts() {
+        // the gate that skips it must not skip a file that does render
+        let test = project(&[
+            ("app/models.py", "class Book:\n    title: str\n"),
+            (
+                "app/views.py",
+                "
+                def show(request):
+                    return render(request, 'app/page.html', {'book': 1})
+                ",
+            ),
+        ]);
+
+        assert_eq!(context(&test, "app/page.html"), ["book"]);
+    }
+
+    #[test]
+    fn re_path_names_routes_too() {
+        let test = project(&[(
+            "app/urls.py",
+            "
+            urlpatterns = [
+                re_path(r'^books/$', index, name='legacy'),
+                path('books/', index, name='index'),
+            ]
+            ",
+        )]);
+
+        let names: Vec<_> = url_names(&test.db, test.db.project())
+            .iter()
+            .map(|url| url.name.as_str())
+            .collect();
+        assert_eq!(names, ["legacy", "index"]);
+    }
+
+    #[test]
+    fn an_inclusion_tags_first_argument_is_a_template_rather_than_a_name() {
+        let test = project(&[(
+            "app/templatetags/app_extras.py",
+            "
+            from django import template
+
+            register = template.Library()
+
+            @register.inclusion_tag('app/card.html')
+            def show_card():
+                '''renders one card.'''
+                return {}
+
+            @register.simple_tag('renamed')
+            def original():
+                return 0
+            ",
+        )]);
+
+        let found: Vec<_> = registrations(&test.db, test.db.project())
+            .iter()
+            .map(|registration| registration.name.as_str())
+            .collect();
+        assert_eq!(found, ["show_card", "renamed"]);
+    }
+
+    #[test]
+    fn a_registered_function_carries_its_docstring() {
+        let test = project(&[(
+            "app/templatetags/app_extras.py",
+            "
+            from django import template
+
+            register = template.Library()
+
+            @register.filter
+            def shout(value):
+                '''upper-cases it.
+
+                and the rest of the docstring is not the summary.
+                '''
+                return value
+            ",
+        )]);
+
+        let documentation = registrations(&test.db, test.db.project())[0]
+            .documentation
+            .clone();
+        assert_eq!(documentation.as_deref(), Some("upper-cases it."));
+    }
+
+    #[test]
+    fn a_library_bound_to_a_name_of_its_own_still_registers() {
+        let test = project(&[(
+            "app/templatetags/app_extras.py",
+            "
+            from django import template
+
+            library = template.Library()
+
+            @library.filter_function
+            def shout(value):
+                return value
+            ",
+        )]);
+
+        let found: Vec<_> = registrations(&test.db, test.db.project())
+            .iter()
+            .map(|registration| (registration.name.as_str(), registration.kind))
+            .collect();
+        assert_eq!(found, [("shout", RegistrationKind::Filter)]);
+    }
+
+    #[test]
+    fn a_module_outside_a_templatetags_package_registers_nothing() {
+        let test = project(&[(
+            "app/extras.py",
+            "
+            from django import template
+
+            register = template.Library()
+
+            @register.filter
+            def shout(value):
+                return value
+            ",
+        )]);
+
+        assert!(registrations(&test.db, test.db.project()).is_empty());
+    }
+}
diff --git a/crates/ty_ide/src/django_template/resolve.rs b/crates/ty_ide/src/django_template/resolve.rs
index cf08b6db90..0cf06d4f57 100644
--- a/crates/ty_ide/src/django_template/resolve.rs
+++ b/crates/ty_ide/src/django_template/resolve.rs
@@ -13,7 +13,9 @@ use ruff_python_ast::find_node::covering_node;
 use ruff_text_size::{Ranged, TextRange, TextSize};
 use ty_project::Db;
 use ty_python_semantic::types::Type;
-use ty_python_semantic::types::ide_support::iterable_element_type;
+use ty_python_semantic::types::ide_support::{
+    iterable_element_type, no_argument_call_return_type, own_class_member_names,
+};
 use ty_python_semantic::types::list_members::{Member, all_members};
 use ty_python_semantic::{HasType, SemanticModel};
 
@@ -181,20 +183,41 @@ pub(crate) fn path_segments<'src>(
         .collect()
 }
 
-/// the type of `name` accessed on `ty`
+/// the type of `name` accessed on `ty`, as the template engine will see it
 ///
 /// django's variable lookup tries a dictionary subscript before an attribute, but
 /// a mapping's keys are values rather than types, so an attribute is all a static
 /// answer can cover.
+///
+/// what it *does* also do is [call what the lookup lands on][resolved], which is
+/// the difference between `author.book_set.all` naming a queryset and naming a
+/// method.
+///
+/// [resolved]: https://docs.djangoproject.com/en/stable/ref/templates/language/#variables
 pub(crate) fn member_type<'db>(db: &'db dyn Db, ty: Type<'db>, name: &str) -> Option<Type<'db>> {
-    members(db, ty)
+    let member = members(db, ty)
         .into_iter()
-        .find(|member| member.name == name)
-        .map(|member| member.ty)
+        .find(|member| member.name == name)?;
+
+    Some(resolved(db, member.ty))
+}
+
+/// what the template engine ends up with once it has resolved a lookup
+///
+/// django calls whatever the lookup found if it is callable, so a member that
+/// takes no arguments contributes its return type rather than its own.
+fn resolved<'db>(db: &'db dyn Db, ty: Type<'db>) -> Type<'db> {
+    no_argument_call_return_type(db, ty).unwrap_or(ty)
 }
 
-/// every attribute a value of type `ty` has, in name order
+/// every attribute a value of type `ty` has
+///
+/// the type's own class comes first and the rest follows, each alphabetically. a
+/// django model inherits several dozen members from `models.Model`, and sorting
+/// its fields in among them puts `title` below `save_base`.
 pub(crate) fn members<'db>(db: &'db dyn Db, ty: Type<'db>) -> Vec<Member<'db>> {
+    let own = own_class_member_names(db, ty);
+
     let mut members: Vec<_> = all_members(db, ty)
         .into_iter()
         // a template can only write a `\w+` name after a dot, so a dunder is both
@@ -202,7 +225,11 @@ pub(crate) fn members<'db>(db: &'db dyn Db, ty: Type<'db>) -> Vec<Member<'db>> {
         .filter(|member| !member.name.starts_with('_'))
         .collect();
 
-    members.sort_unstable_by(|left, right| left.name.cmp(&right.name));
+    members.sort_unstable_by(|left, right| {
+        own.contains(&right.name)
+            .cmp(&own.contains(&left.name))
+            .then_with(|| left.name.cmp(&right.name))
+    });
     members
 }
 
diff --git a/crates/ty_ide/src/django_template/semantic_tokens.rs b/crates/ty_ide/src/django_template/semantic_tokens.rs
index 6c1473e1b4..9d408b935b 100644
--- a/crates/ty_ide/src/django_template/semantic_tokens.rs
+++ b/crates/ty_ide/src/django_template/semantic_tokens.rs
@@ -57,11 +57,15 @@ pub(crate) fn semantic_tokens(
             let text = &source[token.range];
             let (mut token_type, mut modifiers) = classify(token.kind, text)?;
 
-            if let Ok(found) =
-                definitions.binary_search_by_key(&token.range.start(), |(range, _)| range.start())
-                && definitions[found].0 == token.range
+            // a definition's range is the name alone, which for a quoted one —
+            // `{% block "content" %}` — sits *inside* the token rather than
+            // being it
+            let found =
+                definitions.partition_point(|(range, _)| range.start() < token.range.start());
+            if let Some(&(range, kind)) = definitions.get(found)
+                && token.range.contains_range(range)
             {
-                token_type = definitions[found].1;
+                token_type = kind;
                 modifiers |= SemanticTokenModifier::DEFINITION;
             }
 
@@ -86,7 +90,7 @@ fn classify(kind: TokenKind, text: &str) -> Option<(SemanticTokenType, SemanticT
         TokenKind::Comment => (SemanticTokenType::Comment, empty),
         TokenKind::TagName => (
             SemanticTokenType::Keyword,
-            default_library(is_builtin_tag(text)),
+            default_library(is_djangos_tag(text)),
         ),
         TokenKind::FilterName => (
             SemanticTokenType::Function,
@@ -107,7 +111,7 @@ fn classify(kind: TokenKind, text: &str) -> Option<(SemanticTokenType, SemanticT
 /// the builtin table lists a closing tag only as the `closed_by` of the tag it
 /// closes, and a branch tag only as one of its `branches`, but `{% endfor %}` and
 /// `{% empty %}` are as much django's as `{% for %}` is.
-fn is_builtin_tag(name: &str) -> bool {
+fn is_djangos_tag(name: &str) -> bool {
     builtins::tag(name).is_some()
         || builtins::TAGS
             .iter()
@@ -286,6 +290,22 @@ mod tests {
         );
     }
 
+    #[test]
+    fn a_quoted_block_name_is_still_a_definition() {
+        assert_eq!(
+            highlight("{% block \"content\" %}{% endblock %}"),
+            [
+                "operator:{%",
+                "keyword+defaultLibrary:block",
+                "function+definition:\"content\"",
+                "operator:%}",
+                "operator:{%",
+                "keyword+defaultLibrary:endblock",
+                "operator:%}",
+            ]
+        );
+    }
+
     #[test]
     fn keyword_arguments_strings_numbers_and_constants() {
         assert_eq!(
diff --git a/crates/ty_project/src/db/changes.rs b/crates/ty_project/src/db/changes.rs
index c3251bc061..549378292e 100644
--- a/crates/ty_project/src/db/changes.rs
+++ b/crates/ty_project/src/db/changes.rs
@@ -9,6 +9,7 @@ use ruff_db::Db as _;
 use ruff_db::files::{File, Files, system_path_to_file};
 use ruff_db::system::{SystemPath, SystemPathBuf};
 use rustc_hash::FxHashSet;
+use salsa::Setter as _;
 use ty_python_core::program::{FallibleStrategy, Program};
 
 /// Represents the result of applying changes to the project database.
@@ -55,6 +56,9 @@ impl ProjectDatabase {
         let mut removed_paths = BTreeSet::default();
         let mut reload_project = false;
         let mut reload_project_files = false;
+        // Whether the shape of the tree changed, as opposed to the contents of a
+        // file that was already there. See `Project::file_system_revision`.
+        let mut file_system_changed = false;
         // TODO: This should be removed once the incremental checker is ported
         // over to the `ignore` crate, since the `ignore` crate will respect
         // the settings provided in `create_walker`. ---AG
@@ -131,6 +135,8 @@ impl ProjectDatabase {
                 }
 
                 ChangeEvent::Created { kind, path } => {
+                    file_system_changed = true;
+
                     match kind {
                         CreatedKind::File => {
                             if synced_files.insert(path.to_path_buf()) {
@@ -174,6 +180,8 @@ impl ProjectDatabase {
                 }
 
                 ChangeEvent::Deleted { kind, path } => {
+                    file_system_changed = true;
+
                     let is_file = match kind {
                         DeletedKind::File => true,
                         DeletedKind::Directory => false,
@@ -222,6 +230,7 @@ impl ProjectDatabase {
                 }
 
                 ChangeEvent::Rescan => {
+                    file_system_changed = true;
                     reload_project = true;
                     reload_project_files = true;
                     Files::sync_all(self);
@@ -234,6 +243,14 @@ impl ProjectDatabase {
 
         Files::sync_all_recursive(self, sync_recursively);
 
+        // Bumped before the reload paths below, some of which return early.
+        if file_system_changed {
+            let revision = project.file_system_revision(self);
+            project
+                .set_file_system_revision(self)
+                .to(revision.wrapping_add(1));
+        }
+
         if reload_project {
             let new_project_metadata = project.metadata(self).rediscover(self.system());
             match new_project_metadata {
diff --git a/crates/ty_project/src/lib.rs b/crates/ty_project/src/lib.rs
index 50635cad21..726f20d5c0 100644
--- a/crates/ty_project/src/lib.rs
+++ b/crates/ty_project/src/lib.rs
@@ -121,6 +121,17 @@ pub struct Project {
     #[default]
     #[returns(copy)]
     force_exclude_flag: bool,
+
+    /// A counter bumped whenever a file or directory is created or deleted.
+    ///
+    /// The project's file set holds Python files only, so nothing in the database
+    /// changes when a file of any other kind appears or disappears. A query that
+    /// discovers such files by walking the file system — the template and static
+    /// asset discovery the Django template services do — has nothing else to
+    /// depend on, and would otherwise serve its first answer forever.
+    #[default]
+    #[returns(copy)]
+    pub file_system_revision: u64,
 }
 
 /// A progress reporter.
@@ -193,6 +204,7 @@ impl Project {
             .durability(Durability::MEDIUM)
             .open_fileset_durability(Durability::LOW)
             .file_set_durability(Durability::LOW)
+            .file_system_revision_durability(Durability::LOW)
             .new(db)
     }
 
diff --git a/crates/ty_python_semantic/src/types/ide_support.rs b/crates/ty_python_semantic/src/types/ide_support.rs
index 46720b73b0..f444b65a12 100644
--- a/crates/ty_python_semantic/src/types/ide_support.rs
+++ b/crates/ty_python_semantic/src/types/ide_support.rs
@@ -9,6 +9,7 @@ use crate::types::class::{DynamicClassAnchor, DynamicEnumAnchor, DynamicNamedTup
 use crate::types::constraints::ConstraintSetBuilder;
 use crate::types::function::FunctionDecorators;
 use crate::types::generics::GenericContext;
+use crate::types::list_members::all_end_of_scope_members;
 use crate::types::overrides::is_constructor_like_method;
 use crate::types::signatures::{ParametersKind, Signature};
 use crate::types::{
@@ -2448,6 +2449,39 @@ pub fn iterable_element_type<'db>(db: &'db dyn Db, ty: Type<'db>) -> Option<Type
     Some(ty.try_iterate(db).ok()?.homogeneous_element_type(db))
 }
 
+/// What calling `ty` with no arguments gives, or `None` when it can't be called
+/// that way.
+///
+/// Written for django templates, whose variable resolution calls whatever a
+/// lookup lands on: `{{ author.get_full_name }}` renders the name rather than
+/// the method, and `{% for book in author.book_set.all %}` iterates the queryset
+/// rather than the manager's method. Attribute access alone stops at the method
+/// and every one of those traversals dead-ends.
+pub fn no_argument_call_return_type<'db>(db: &'db dyn Db, ty: Type<'db>) -> Option<Type<'db>> {
+    ty.try_call(db, &CallArguments::none())
+        .ok()
+        .map(|bindings| bindings.return_type(db))
+}
+
+/// The names `ty`'s own class declares, as opposed to the ones it inherits.
+///
+/// Written for django templates, where a model's own fields have to be told
+/// apart from the several dozen members `models.Model` brings with it. The
+/// fields are what the template was written against; sorting them in among the
+/// framework's machinery is nearly the same as not offering them.
+pub fn own_class_member_names<'db>(db: &'db dyn Db, ty: Type<'db>) -> FxIndexSet<Name> {
+    let Type::NominalInstance(instance) = ty else {
+        return FxIndexSet::default();
+    };
+    let Some((class, _)) = instance.class(db).static_class_literal(db) else {
+        return FxIndexSet::default();
+    };
+
+    all_end_of_scope_members(db, class.body_scope(db))
+        .map(|member| member.member.name)
+        .collect()
+}
+
 /// The extra arms the typing spec's numeric promotion adds to a type expression
 /// that already evaluated to `ty`, rendered as they would be spelled.
 ///
diff --git a/crates/ty_server/src/capabilities.rs b/crates/ty_server/src/capabilities.rs
index 3c13131959..fce472ab62 100644
--- a/crates/ty_server/src/capabilities.rs
+++ b/crates/ty_server/src/capabilities.rs
@@ -476,9 +476,8 @@ pub(crate) fn server_capabilities(
             // positions in a template are right after `{%`, `{{` and `|`, and
             // none of them is a word character the client would trigger on by
             // itself. LSP has no way to vary these per language, so python
-            // documents see them too — harmlessly, since a completion request
-            // there is answered from the cursor's position rather than from
-            // whichever character triggered it.
+            // documents see the requests too — and turn them away, see
+            // `triggered_by_a_template_character`.
             trigger_characters: Some(vec![
                 '.'.to_string(),
                 '"'.to_string(),
diff --git a/crates/ty_server/src/server/api/requests/completion.rs b/crates/ty_server/src/server/api/requests/completion.rs
index c479c58517..db35fe622a 100644
--- a/crates/ty_server/src/server/api/requests/completion.rs
+++ b/crates/ty_server/src/server/api/requests/completion.rs
@@ -59,6 +59,14 @@ impl BackgroundDocumentRequestHandler for CompletionRequestHandler {
         if snapshot.is_django_template() {
             return Ok(django_template_completions(db, snapshot, file, offset));
         }
+        if triggered_by_a_template_character(&params) {
+            // `{`, `%` and `|` are registered as trigger characters for the sake
+            // of django templates, and LSP has no way to register them for one
+            // language only. python gets the requests too, and a popup listing
+            // every name in scope the moment the user opens a dict literal or
+            // writes a union is not what they asked for.
+            return Ok(None);
+        }
 
         let client_capabilities = snapshot.resolved_client_capabilities();
         let completions = completion(
@@ -171,6 +179,24 @@ impl RetriableRequestHandler for CompletionRequestHandler {
     const RETRY_ON_CANCELLATION: bool = true;
 }
 
+/// The characters that only ever open a django template construct.
+///
+/// Kept in step with the trigger characters the server registers in
+/// `capabilities`, where the reason they are registered at all is spelled out.
+const TEMPLATE_TRIGGER_CHARACTERS: &[&str] = &["{", "%", "|"];
+
+/// Whether this request was triggered by typing a character that means nothing
+/// outside a django template.
+fn triggered_by_a_template_character(params: &CompletionParams) -> bool {
+    params.context.as_ref().is_some_and(|context| {
+        context.trigger_kind == lsp_types::CompletionTriggerKind::TriggerCharacter
+            && context
+                .trigger_character
+                .as_deref()
+                .is_some_and(|character| TEMPLATE_TRIGGER_CHARACTERS.contains(&character))
+    })
+}
+
 /// The completion response for a django template document.
 ///
 /// Unlike the python ones, every template completion carries the range it
diff --git a/crates/ty_server/src/server/api/requests/semantic_tokens.rs b/crates/ty_server/src/server/api/requests/semantic_tokens.rs
index 06c21ff5ee..4475d80f25 100644
--- a/crates/ty_server/src/server/api/requests/semantic_tokens.rs
+++ b/crates/ty_server/src/server/api/requests/semantic_tokens.rs
@@ -46,8 +46,7 @@ impl BackgroundDocumentRequestHandler for SemanticTokensRequestHandler {
         // because all ranges in the response must be within this **this document**.
         let mut cell_range = None;
 
-        if !snapshot.is_django_template()
-            && snapshot.document().is_cell()
+        if snapshot.document().is_cell()
             && let Some(notebook_document) = db.notebook_document(file)
             && let Some(notebook) = source_text(db, file).as_notebook()
         {
diff --git a/crates/ty_server/tests/e2e/django_templates.rs b/crates/ty_server/tests/e2e/django_templates.rs
index 7f7f908f80..c90d1179db 100644
--- a/crates/ty_server/tests/e2e/django_templates.rs
+++ b/crates/ty_server/tests/e2e/django_templates.rs
@@ -7,8 +7,8 @@
 
 use anyhow::Result;
 use lsp_types::{
-    DocumentDiagnosticReport, LanguageKind, Position, TextDocumentIdentifier,
-    TextDocumentPositionParams,
+    DocumentDiagnosticReport, FileChangeType, FileEvent, LanguageKind, Position,
+    TextDocumentIdentifier, TextDocumentPositionParams,
 };
 use ruff_db::system::SystemPath;
 
@@ -178,6 +178,39 @@ fn a_template_navigates_to_the_template_it_extends() -> Result<()> {
     Ok(())
 }
 
+#[test]
+fn a_template_created_during_the_session_is_offered_to_an_extends() -> Result<()> {
+    // discovering templates means walking the file system, which salsa cannot
+    // see into: without something to invalidate the walk the server would go on
+    // offering the set of templates that existed when it started
+    let mut server = server("{% extends '' %}\n")?;
+    let uri = template_uri(&server);
+
+    let offered = |server: &mut TestServer| -> Vec<String> {
+        server
+            .completion_request(&uri, Position::new(0, 12))
+            .iter()
+            .map(|completion| completion.label.clone())
+            .collect()
+    };
+
+    assert!(!offered(&mut server).contains(&"blog/card.html".to_string()));
+
+    let created = SystemPath::new("src/blog/templates/blog/card.html");
+    server.write_file(created, "<p>a card</p>\n")?;
+    server.did_change_watched_files(vec![FileEvent {
+        uri: server.file_uri(created),
+        kind: FileChangeType::Created,
+    }]);
+
+    assert!(
+        offered(&mut server).contains(&"blog/card.html".to_string()),
+        "a template created after the server started is still a template"
+    );
+
+    Ok(())
+}
+
 #[test]
 fn a_template_is_never_type_checked_as_python() -> Result<()> {
     // every line of this would be a python syntax error
diff --git a/crates/ty_server/tests/e2e/main.rs b/crates/ty_server/tests/e2e/main.rs
index ffaf865f97..55aea01c25 100644
--- a/crates/ty_server/tests/e2e/main.rs
+++ b/crates/ty_server/tests/e2e/main.rs
@@ -776,7 +776,6 @@ impl TestServer {
         self.test_context.root().join(path)
     }
 
-    #[expect(dead_code)]
     pub(crate) fn write_file(
         &self,
         path: impl AsRef<SystemPath>,
diff --git a/docs/basedpython/frameworks/django-templates.md b/docs/basedpython/frameworks/django-templates.md
index 023cea7912..217b5643e6 100644
--- a/docs/basedpython/frameworks/django-templates.md
+++ b/docs/basedpython/frameworks/django-templates.md
@@ -13,7 +13,7 @@ what is offered depends on where the caret is.
 | `{% ‸ %}`           | tag names: django's builtins, the project's own registered tags, and the `{% end… %}` that closes the block you're in |
 | `{{ x\|‸ }}`        | filter names: django's builtins and the project's own registered filters                                              |
 | `{{ ‸ }}`           | the variables the view puts in this template's context, plus the names the template itself binds                      |
-| `{{ book.‸ }}`      | the attributes of `book`'s type — for a django model, that's its fields                                               |
+| `{{ book.‸ }}`      | the attributes of `book`'s type — for a django model its own fields lead, ahead of what `models.Model` brings         |
 | `{% extends '‸' %}` | the project's template paths                                                                                          |
 | `{% include '‸' %}` | the project's template paths                                                                                          |
 | `{% url '‸' %}`     | the project's route names, namespaced by `app_name`                                                                   |
@@ -26,6 +26,8 @@ the tag that closes the block you're inside is always offered first, so `{% for
 
 a tag or filter from a library the template hasn't loaded comes with the `{% load %}` it needs as an extra edit, written below the `{% extends %}` if there is one.
 
+`{% partialdef %}` and `{% partial %}` are django's own from 6.0 and need no `{% load %}`. on an older django they come from [django-template-partials](https://github.com/carltongibson/django-template-partials), which does need one — the tags are offered either way, but the load is not written for you.
+
 ### go-to-definition
 
 | on                                    | goes to                                                             |
@@ -68,6 +70,17 @@ def post(request):
 
 the server finds the `render()` call that names `blog/post.html`, reads `book` out of its context dict, asks the type checker what that expression is — a `Book` — and then walks `author` and `name` through the model's fields. django's field machinery is already understood (see [django support](django.md)), so a `ForeignKey` traverses and a `null=True` field is optional, exactly as in python.
 
+a lookup that lands on something callable is called, exactly as django calls it, so the idioms that traverse through a method resolve:
+
+```django
+{{ book.get_absolute_url }}                       {# `str`, not the method #}
+{% for c in book.author.book_set.all %}           {# a `Book`, through the manager #}
+    {{ c.title }}
+{% endfor %}
+```
+
+a method that needs an argument is not called — django renders nothing for it, and neither does the server offer anything past it.
+
 the same works through the template's own bindings:
 
 ```django
@@ -89,9 +102,9 @@ two views rendering the same template both contribute; a name they agree on appe
 
 ## how a template is recognised
 
-the editor usually says so: `django-html`, `htmldjango`, `django-txt` and `jinja-html` are all taken as django templates.
+the editor usually says so: `django`, `django-html`, `django-txt`, `htmldjango` and `jinja-html` are all taken as django templates.
 
-when the editor just calls the file `html` — which is what plain vs code does — the path decides: a file with a template-ish extension (`.html`, `.htm`, `.txt`, `.xml`, `.django`, `.jinja`) somewhere under a directory named `templates` is a django template. ordinary html elsewhere in the project is left alone.
+when the editor just calls the file `html` — which is what plain vs code does — the path decides: a file with a template-ish extension (`.html`, `.htm`, `.txt`, `.xml`, `.django`, `.dj`, `.jinja`) somewhere under a directory named `templates` is a django template. ordinary html elsewhere in the project is left alone.
 
 template directories, static directories and tag libraries are found by their conventional names, which is what django's own app-directories loaders use:
 
@@ -105,9 +118,11 @@ template directories, static directories and tag libraries are found by their co
 
 **a `TEMPLATES` setting is not read.** template directories are found by name rather than from `settings.py`, so a `DIRS` entry pointing somewhere else is not picked up.
 
-**dictionary lookups don't resolve.** django tries a subscript before an attribute, so `{{ mapping.key }}` works at runtime, but a mapping's keys are values rather than types and completions can only offer attributes.
+**the context has to be written where it is passed.** the names are read out of the dict literal in the `render()` call or the view class, so a context built somewhere else and passed by name — `return render(request, "…", context)` — contributes nothing.
 
-**callables are not called.** django calls `{{ author.get_full_name }}` for you; the server reports the method's type rather than its return type, so attributes past a call don't resolve.
+**a member django refuses to call is still offered.** django won't call `save()` or `delete()` from a template — they carry `alters_data` — but `django-stubs` doesn't record that, so there is nothing to read it from. they appear in the list, below the model's own fields.
+
+**dictionary lookups don't resolve.** django tries a subscript before an attribute, so `{{ mapping.key }}` works at runtime, but a mapping's keys are values rather than types and completions can only offer attributes.
 
 **`{% url %}` namespaces come from `app_name`.** a namespace given at the `include()` instead is not applied.
 
@@ -115,4 +130,4 @@ template directories, static directories and tag libraries are found by their co
 
 - [django support](django.md) — the type checker's understanding of models, fields and queries
 - [django template language](https://docs.djangoproject.com/en/stable/ref/templates/language/)
-- [django template partials](https://docs.djangoproject.com/en/stable/ref/templates/builtins/#partialdef)
+- [django-template-partials](https://github.com/carltongibson/django-template-partials) — where `{% partialdef %}` came from before django 6.0

From 7fd89974273c4a6dbfa01458e38c4766bb4524ad Mon Sep 17 00:00:00 2001
From: KotlinIsland <65446343+kotlinisland@users.noreply.github.com>
Date: Sat, 8 Aug 2026 21:38:32 +1000
Subject: [PATCH 03/16] a template's names read from python too, and more of
 its editor surface

a drf router names routes that no `path(..., name=)` call spells, so they are
indexed from `register()` instead. template names and route names in python source
are recognised as the names they are. and a template answers hover, document
symbols and folding
---
 crates/ty_ide/src/completion.rs               | 220 +++++++
 crates/ty_ide/src/django_template.rs          |  88 ++-
 .../ty_ide/src/django_template/completion.rs  |  37 ++
 crates/ty_ide/src/django_template/folding.rs  |  84 +++
 crates/ty_ide/src/django_template/goto.rs     |   2 +-
 crates/ty_ide/src/django_template/hover.rs    | 580 ++++++++++++++++++
 crates/ty_ide/src/django_template/index.rs    |   5 +
 crates/ty_ide/src/django_template/project.rs  | 552 ++++++++++++++++-
 crates/ty_ide/src/django_template/python.rs   | 220 +++++++
 crates/ty_ide/src/django_template/symbols.rs  | 147 +++++
 crates/ty_ide/src/goto_definition.rs          | 178 ++++++
 crates/ty_ide/src/lib.rs                      |   6 +-
 .../src/server/api/requests/completion.rs     |  13 +
 .../server/api/requests/document_symbols.rs   |  92 ++-
 .../src/server/api/requests/folding_range.rs  |  10 +-
 .../src/server/api/requests/hover.rs          |  29 +-
 .../ty_server/tests/e2e/django_templates.rs   |  67 ++
 crates/ty_server/tests/e2e/main.rs            |  22 +-
 .../frameworks/django-templates.md            |  30 +-
 19 files changed, 2329 insertions(+), 53 deletions(-)
 create mode 100644 crates/ty_ide/src/django_template/folding.rs
 create mode 100644 crates/ty_ide/src/django_template/hover.rs
 create mode 100644 crates/ty_ide/src/django_template/python.rs
 create mode 100644 crates/ty_ide/src/django_template/symbols.rs

diff --git a/crates/ty_ide/src/completion.rs b/crates/ty_ide/src/completion.rs
index 145446f44b..31ccbd732b 100644
--- a/crates/ty_ide/src/completion.rs
+++ b/crates/ty_ide/src/completion.rs
@@ -27,6 +27,7 @@ use ty_python_semantic::{
     types::{CycleDetector, KnownClass, Type},
 };
 
+use crate::django_template::django_string_completions;
 use crate::docstring::Docstring;
 use crate::goto::Definitions;
 use crate::importer::{ImportRequest, Importer};
@@ -62,6 +63,7 @@ pub fn completion<'db>(
         let mut completions =
             Completions::new(db, CollectionContext::none(), UserQuery::fuzzy(None));
 
+        add_django_name_completions(db, &context.cursor, &mut completions);
         add_string_literal_completions(
             &model,
             string_expr,
@@ -311,6 +313,12 @@ pub struct Completion<'db> {
     pub insert: Option<CompactString>,
     /// The format of [`Self::insert`].
     pub insert_text_format: CompletionInsertTextFormat,
+    /// The range that [`Self::insert`] replaces.
+    ///
+    /// This is only set when the client's own idea of the word under the
+    /// cursor would be wrong, as it is for a django template path or a
+    /// namespaced url name.
+    pub replace: Option<TextRange>,
     /// The type of this completion, if available.
     ///
     /// Generally speaking, this is always available
@@ -391,6 +399,7 @@ struct CompletionBuilder<'db> {
     name: CompactString,
     qualified: Option<CompactString>,
     insert: Option<CompactString>,
+    replace: Option<TextRange>,
     ty: Option<Type<'db>>,
     kind: Option<CompletionKind>,
     module_name: Option<&'db ModuleName>,
@@ -415,6 +424,7 @@ impl<'db> CompletionBuilder<'db> {
             name: name.into(),
             qualified: None,
             insert: None,
+            replace: None,
             ty: None,
             kind: None,
             module_name: None,
@@ -533,6 +543,7 @@ impl<'db> CompletionBuilder<'db> {
             qualified: self.qualified,
             insert,
             insert_text_format,
+            replace: self.replace,
             ty: self.ty,
             kind,
             module_name: self.module_name,
@@ -557,6 +568,11 @@ impl<'db> CompletionBuilder<'db> {
         self
     }
 
+    fn replace(mut self, range: TextRange) -> CompletionBuilder<'db> {
+        self.replace = Some(range);
+        self
+    }
+
     fn ty(mut self, ty: impl Into<Option<Type<'db>>>) -> CompletionBuilder<'db> {
         self.ty = ty.into();
         self
@@ -2276,6 +2292,26 @@ fn position_of(component: FormatSpecComponent) -> usize {
         .unwrap_or(0)
 }
 
+/// Adds the django names the string literal under the cursor could be spelling.
+///
+/// A template name and a url name are ordinary strings to python, so only the
+/// literal's position tells them apart from any other. Nothing is looked up
+/// unless that position is one django reads a name from.
+fn add_django_name_completions<'db>(
+    db: &'db dyn Db,
+    cursor: &ContextCursor<'_>,
+    completions: &mut Completions<'db>,
+) {
+    for candidate in django_string_completions(db, cursor.covering_node.ancestors()) {
+        completions.add_skip_query(
+            Completion::builder(candidate.name)
+                .kind(candidate.kind)
+                .replace(candidate.range)
+                .context_specific(true),
+        );
+    }
+}
+
 fn add_string_literal_completions<'db>(
     model: &SemanticModel<'db>,
     string_expr: &ast::ExprStringLiteral,
@@ -8381,6 +8417,190 @@ x = y = func(lambda: "<CURSOR>")
         );
     }
 
+    /// A django project whose `blog/views.py` carries the cursor.
+    fn django_test_builder(views: &str) -> CompletionTestBuilder {
+        CursorTest::builder()
+            .source("blog/templates/blog/post.html", "<h1></h1>")
+            .source("blog/templates/blog/list.html", "<ul></ul>")
+            .source(
+                "blog/urls.py",
+                r#"
+app_name = "blog"
+
+class BookViewSet: ...
+
+router = DefaultRouter()
+router.register("books", BookViewSet, basename="book")
+
+urlpatterns = [
+    path("<int:pk>/", detail, name="detail"),
+    path("", index, name="index"),
+]
+"#,
+            )
+            .source("blog/views.py", views)
+            .completion_test_builder()
+    }
+
+    #[test]
+    fn django_render_offers_the_projects_templates() {
+        let builder = django_test_builder(
+            r#"
+def show(request):
+    return render(request, "<CURSOR>")
+"#,
+        );
+
+        assert_snapshot!(builder.build().snapshot(), @"
+        blog/list.html
+        blog/post.html
+        ");
+    }
+
+    #[test]
+    fn django_render_offers_templates_for_the_keyword_form_too() {
+        let builder = django_test_builder(
+            r#"
+def show(request):
+    return shortcuts.render(request, template_name="<CURSOR>")
+"#,
+        );
+
+        assert_snapshot!(builder.build().snapshot(), @"
+        blog/list.html
+        blog/post.html
+        ");
+    }
+
+    #[test]
+    fn django_template_response_names_a_template_just_as_render_does() {
+        let builder = django_test_builder(
+            r#"
+def show(request):
+    return TemplateResponse(request, "<CURSOR>")
+"#,
+        );
+
+        assert_snapshot!(builder.build().snapshot(), @"
+        blog/list.html
+        blog/post.html
+        ");
+    }
+
+    #[test]
+    fn django_a_view_classs_template_name_names_a_template() {
+        let builder = django_test_builder(
+            r#"
+class PostDetail(DetailView):
+    template_name = "<CURSOR>"
+"#,
+        );
+
+        assert_snapshot!(builder.build().snapshot(), @"
+        blog/list.html
+        blog/post.html
+        ");
+    }
+
+    #[test]
+    fn django_a_template_name_outside_a_class_names_nothing() {
+        let builder = django_test_builder(
+            r#"
+template_name = "<CURSOR>"
+"#,
+        );
+
+        assert_snapshot!(builder.build().snapshot(), @"<No completions found>");
+    }
+
+    #[test]
+    fn django_reverse_offers_the_projects_url_names() {
+        let builder = django_test_builder(
+            r#"
+def show(request):
+    return reverse("<CURSOR>")
+"#,
+        );
+
+        assert_snapshot!(builder.build().snapshot(), @"
+        blog:book-detail
+        blog:book-list
+        blog:detail
+        blog:index
+        ");
+    }
+
+    #[test]
+    fn django_reverse_lazy_offers_url_names_too() {
+        let builder = django_test_builder(
+            r#"
+url = urls.reverse_lazy("<CURSOR>")
+"#,
+        );
+
+        assert_snapshot!(builder.build().snapshot(), @"
+        blog:book-detail
+        blog:book-list
+        blog:detail
+        blog:index
+        ");
+    }
+
+    #[test]
+    fn django_redirect_offers_url_names() {
+        let builder = django_test_builder(
+            r#"
+def show(request):
+    return redirect("<CURSOR>")
+"#,
+        );
+
+        assert_snapshot!(builder.build().snapshot(), @"
+        blog:book-detail
+        blog:book-list
+        blog:detail
+        blog:index
+        ");
+    }
+
+    #[test]
+    fn django_redirect_offers_nothing_for_a_url_path() {
+        // a redirect takes a path as readily as a route name, and a path is the
+        // one thing a route name never is
+        let builder = django_test_builder(
+            r#"
+def show(request):
+    return redirect("/blog/<CURSOR>")
+"#,
+        );
+
+        assert_snapshot!(builder.build().snapshot(), @"<No completions found>");
+    }
+
+    #[test]
+    fn django_a_string_in_no_recognised_position_offers_nothing() {
+        let builder = django_test_builder(
+            r#"
+def show(request):
+    return render(request, "blog/post.html", {"title": "<CURSOR>"})
+"#,
+        );
+
+        assert_snapshot!(builder.build().snapshot(), @"<No completions found>");
+    }
+
+    #[test]
+    fn django_the_wrong_argument_of_a_render_offers_nothing() {
+        let builder = django_test_builder(
+            r#"
+def show(request):
+    return render("<CURSOR>", "blog/post.html")
+"#,
+        );
+
+        assert_snapshot!(builder.build().snapshot(), @"<No completions found>");
+    }
+
     #[test]
     fn typevar_with_upper_bound() {
         let builder = completion_test_builder(
diff --git a/crates/ty_ide/src/django_template.rs b/crates/ty_ide/src/django_template.rs
index 0033e98062..a199c9db03 100644
--- a/crates/ty_ide/src/django_template.rs
+++ b/crates/ty_ide/src/django_template.rs
@@ -8,17 +8,30 @@
 //! `templatetags` modules. so this module owns a small template front end of its
 //! own ([`lexer`], [`index`]) and spends the rest of its effort joining it to the
 //! python side ([`project`]).
+//!
+//! the join runs both ways. [`python`] is the other direction: the template name
+//! a view renders and the route name a view reverses are plain strings to python,
+//! and it is what lets the python services see them for what they are.
 
 mod builtins;
 mod completion;
+mod folding;
 mod goto;
+mod hover;
 mod index;
 mod lexer;
 mod project;
+mod python;
 mod resolve;
 mod semantic_tokens;
+mod symbols;
 
 pub use completion::{TemplateCompletion, TemplateEdit};
+pub use hover::{DisplayTemplateHover, TemplateHover};
+pub(crate) use python::{
+    string_completions as django_string_completions, string_definition as django_string_definition,
+};
+pub use symbols::TemplateSymbol;
 
 use ruff_db::files::File;
 use ruff_db::source::source_text;
@@ -27,7 +40,7 @@ use ruff_text_size::{TextRange, TextSize};
 use ty_project::Db;
 
 use crate::semantic_tokens::SemanticTokens;
-use crate::{NavigationTargets, RangedValue};
+use crate::{FoldingRange, NavigationTargets, RangedValue};
 
 use index::TemplateIndex;
 
@@ -100,6 +113,27 @@ pub fn django_template_goto_definition(
     goto::goto_definition(db, file, template_index(db, file), source.as_str(), offset)
 }
 
+/// what the thing at `offset` of `file` is, read as a django template
+pub fn django_template_hover(
+    db: &dyn Db,
+    file: File,
+    offset: TextSize,
+) -> Option<RangedValue<TemplateHover>> {
+    let source = source_text(db, file);
+    hover::hover(db, file, template_index(db, file), source.as_str(), offset)
+}
+
+/// the outline of `file`, read as a django template
+pub fn django_template_document_symbols(db: &dyn Db, file: File) -> Vec<TemplateSymbol> {
+    symbols::document_symbols(template_index(db, file))
+}
+
+/// the foldable ranges of `file`, read as a django template
+pub fn django_template_folding_ranges(db: &dyn Db, file: File) -> Vec<FoldingRange> {
+    let source = source_text(db, file);
+    folding::folding_ranges(template_index(db, file), source.as_str())
+}
+
 /// the templates `index` extends, nearest ancestor first
 ///
 /// a template whose parent chain has a cycle in it would not render, but the
@@ -153,8 +187,12 @@ pub(crate) mod tests {
     use ruff_text_size::TextSize;
     use ty_project::{ProjectMetadata, TestDb};
 
+    use crate::MarkupKind;
+
     use super::{
-        django_template_completions, django_template_goto_definition, is_django_template_path,
+        TemplateSymbol, django_template_completions, django_template_document_symbols,
+        django_template_folding_ranges, django_template_goto_definition, django_template_hover,
+        is_django_template_path,
     };
 
     /// a project whose files are written out, with the cursor marked by
@@ -240,6 +278,52 @@ pub(crate) mod tests {
                 })
                 .collect()
         }
+
+        /// the hover at the cursor, as markdown, or `""` where there is none
+        pub(crate) fn hover(&self) -> String {
+            django_template_hover(&self.db, self.file, self.offset)
+                .map(|hover| hover.display(MarkupKind::Markdown).to_string())
+                .unwrap_or_default()
+        }
+
+        /// the template's outline, one line per symbol, nesting indented
+        pub(crate) fn symbols(&self) -> Vec<String> {
+            fn render(symbols: &[TemplateSymbol], depth: usize, lines: &mut Vec<String>) {
+                for symbol in symbols {
+                    lines.push(format!(
+                        "{:indent$}{:?} {}",
+                        "",
+                        symbol.kind,
+                        symbol.name,
+                        indent = depth * 2
+                    ));
+                    render(&symbol.children, depth + 1, lines);
+                }
+            }
+
+            let mut lines = Vec::new();
+            render(
+                &django_template_document_symbols(&self.db, self.file),
+                0,
+                &mut lines,
+            );
+            lines
+        }
+
+        /// each foldable range, as the tags that open and close it
+        pub(crate) fn folds(&self) -> Vec<String> {
+            let source = ruff_db::source::source_text(&self.db, self.file);
+
+            django_template_folding_ranges(&self.db, self.file)
+                .into_iter()
+                .map(|fold| {
+                    let text = &source[fold.range];
+                    let first = text.lines().next().unwrap_or_default().trim();
+                    let last = text.lines().next_back().unwrap_or_default().trim();
+                    format!("{first} … {last}")
+                })
+                .collect()
+        }
     }
 
     #[test]
diff --git a/crates/ty_ide/src/django_template/completion.rs b/crates/ty_ide/src/django_template/completion.rs
index 331860d0e4..d9ef6a0d96 100644
--- a/crates/ty_ide/src/django_template/completion.rs
+++ b/crates/ty_ide/src/django_template/completion.rs
@@ -1017,6 +1017,43 @@ mod tests {
         );
     }
 
+    #[test]
+    fn url_offers_the_routes_a_rest_framework_router_generates() {
+        let test = TemplateTest::new(&[
+            (
+                "api/views.py",
+                "
+                class BookViewSet:
+                    queryset = Book.objects.all()
+
+                    @action(detail=True)
+                    def mark_read(self, request, pk=None): ...
+                ",
+            ),
+            (
+                "api/urls.py",
+                "
+                from api.views import BookViewSet
+
+                router = DefaultRouter()
+                router.register('books', BookViewSet)
+
+                urlpatterns = router.urls
+                ",
+            ),
+            ("blog/templates/blog/post.html", "{% url '<CURSOR>' %}"),
+        ]);
+
+        assert_eq!(
+            test.detailed(),
+            [
+                "book-list — books",
+                "book-detail — books",
+                "book-mark-read — books"
+            ]
+        );
+    }
+
     #[test]
     fn static_offers_the_projects_assets() {
         let completions = project("{% load static %}{% static '<CURSOR>' %}").completions();
diff --git a/crates/ty_ide/src/django_template/folding.rs b/crates/ty_ide/src/django_template/folding.rs
new file mode 100644
index 0000000000..2a94cef551
--- /dev/null
+++ b/crates/ty_ide/src/django_template/folding.rs
@@ -0,0 +1,84 @@
+//! folding ranges for django templates
+//!
+//! a template's foldable regions are exactly its blocks — `{% for %}` to
+//! `{% endfor %}`, `{% block %}` to `{% endblock %}`, and whatever the project's
+//! own block tags are — which the index has already paired up.
+
+use crate::FoldingRange;
+
+use super::index::TemplateIndex;
+
+/// one foldable range per block `index` spans
+pub(crate) fn folding_ranges(index: &TemplateIndex, source: &str) -> Vec<FoldingRange> {
+    index
+        .spans()
+        .iter()
+        // a block whose closing tag has not been typed yet runs to the end of the
+        // template, and folding the rest of the file away is not what the user is
+        // in the middle of asking for
+        .filter(|block| block.closed)
+        .map(|block| block.full_range)
+        .filter(|range| {
+            let text = &source[*range];
+            text.contains('\n') || text.contains('\r')
+        })
+        .map(FoldingRange::from)
+        .collect()
+}
+
+#[cfg(test)]
+mod tests {
+    use crate::django_template::tests::TemplateTest;
+
+    fn template(source: &str) -> TemplateTest {
+        TemplateTest::new(&[("blog/templates/blog/post.html", source)])
+    }
+
+    #[test]
+    fn a_block_tag_folds_from_its_opening_tag_to_its_closing_one() {
+        let test = template(
+            "<CURSOR>{% block content %}\n\
+             <p>a</p>\n\
+             {% endblock %}\n",
+        );
+
+        assert_eq!(test.folds(), ["{% block content %} … {% endblock %}"]);
+    }
+
+    #[test]
+    fn every_block_tag_folds() {
+        let test = template(
+            "<CURSOR>{% for book in books %}\n\
+             {% if book %}\n\
+             a\n\
+             {% endif %}\n\
+             {% endfor %}\n",
+        );
+
+        assert_eq!(
+            test.folds(),
+            [
+                "{% for book in books %} … {% endfor %}",
+                "{% if book %} … {% endif %}"
+            ]
+        );
+    }
+
+    #[test]
+    fn a_block_written_on_one_line_does_not_fold() {
+        assert!(
+            template("<CURSOR>{% block content %}a{% endblock %}\n")
+                .folds()
+                .is_empty()
+        );
+    }
+
+    #[test]
+    fn a_block_that_was_never_closed_does_not_fold() {
+        assert!(
+            template("<CURSOR>{% block content %}\na\n")
+                .folds()
+                .is_empty()
+        );
+    }
+}
diff --git a/crates/ty_ide/src/django_template/goto.rs b/crates/ty_ide/src/django_template/goto.rs
index 3e26bd9728..caffb91fc0 100644
--- a/crates/ty_ide/src/django_template/goto.rs
+++ b/crates/ty_ide/src/django_template/goto.rs
@@ -242,7 +242,7 @@ fn definition_in_chain(
 ///
 /// `inclusive` keeps `token` itself, for a name whose own type is wanted; leaving
 /// it out gives the type the name is an attribute *of*.
-fn path_up_to<'src>(
+pub(super) fn path_up_to<'src>(
     source: &'src str,
     tokens: &[Token],
     token: Token,
diff --git a/crates/ty_ide/src/django_template/hover.rs b/crates/ty_ide/src/django_template/hover.rs
new file mode 100644
index 0000000000..b5e6ec3d0b
--- /dev/null
+++ b/crates/ty_ide/src/django_template/hover.rs
@@ -0,0 +1,580 @@
+//! hover for django templates
+//!
+//! a template says very little about itself: `{{ book.title }}` is three words and
+//! a dot, and what makes it meaningful is the model behind `book`, the view that
+//! put it there and the filter library the `|` reaches into. hover is where all of
+//! that is already known and only has to be written down, so every answer here is
+//! a lookup the other features have made already — a type from [`super::resolve`],
+//! a documentation string from [`super::builtins`] or from the project's own
+//! registrations, a template the loader resolved.
+
+use std::fmt::{self, Formatter};
+
+use ruff_db::files::{File, FileRange};
+use ruff_text_size::TextSize;
+use ty_project::Db;
+
+use crate::{MarkupKind, RangedValue};
+
+use super::builtins;
+use super::goto::path_up_to;
+use super::index::TemplateIndex;
+use super::lexer::{ConstructKind, Token, TokenKind, string_contents};
+use super::project::{self, RegistrationKind};
+use super::resolve::{self, Origin};
+
+/// the language a template construct is rendered as, for a client that knows it
+const DJANGO: &str = "django-html";
+
+/// what a hover over a template says
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct TemplateHover {
+    contents: Vec<Content>,
+}
+
+impl TemplateHover {
+    /// render the hover in the markup the client asked for
+    pub fn display(&self, kind: MarkupKind) -> DisplayTemplateHover<'_> {
+        DisplayTemplateHover { hover: self, kind }
+    }
+}
+
+/// one section of a hover
+#[derive(Debug, Clone, PartialEq, Eq)]
+enum Content {
+    /// source written in `language`
+    Code {
+        language: &'static str,
+        text: String,
+    },
+    /// prose, in markdown
+    Text(String),
+}
+
+pub struct DisplayTemplateHover<'a> {
+    hover: &'a TemplateHover,
+    kind: MarkupKind,
+}
+
+impl fmt::Display for DisplayTemplateHover<'_> {
+    fn fmt(&self, f: &mut Formatter<'_>) -> fmt::Result {
+        for (position, content) in self.hover.contents.iter().enumerate() {
+            if position > 0 {
+                write!(f, "{}", self.kind.horizontal_line())?;
+            }
+
+            match content {
+                Content::Code { language, text } => {
+                    write!(f, "{}", self.kind.fenced_code_block(text, language))?;
+                }
+                Content::Text(text) => write!(f, "{text}")?,
+            }
+        }
+
+        Ok(())
+    }
+}
+
+/// what the thing at `offset` of the template `file` is
+pub(crate) fn hover(
+    db: &dyn Db,
+    file: File,
+    index: &TemplateIndex,
+    source: &str,
+    offset: TextSize,
+) -> Option<RangedValue<TemplateHover>> {
+    let construct = index.lexed().construct_at(offset)?;
+    if construct.kind == ConstructKind::Comment {
+        return None;
+    }
+
+    let tokens = index.lexed().construct_tokens(construct);
+    let token = *tokens
+        .iter()
+        .find(|token| token.range.contains_inclusive(offset))?;
+
+    let site = Site {
+        db,
+        file,
+        index,
+        source,
+        offset,
+        tag: construct.name.map_or("", |range| &source[range]),
+        tokens,
+        token,
+    };
+
+    let contents = site.contents();
+
+    (!contents.is_empty()).then(|| RangedValue {
+        range: FileRange::new(file, token.range),
+        value: TemplateHover { contents },
+    })
+}
+
+/// the one token the hover is about, with everything needed to interpret it
+struct Site<'a> {
+    db: &'a dyn Db,
+    file: File,
+    index: &'a TemplateIndex,
+    source: &'a str,
+    offset: TextSize,
+    /// the name of the tag the token sits in, or `""` outside a tag
+    tag: &'a str,
+    /// the tokens of the construct the token sits in
+    tokens: &'a [Token],
+    token: Token,
+}
+
+impl Site<'_> {
+    fn text(&self) -> &str {
+        &self.source[self.token.range]
+    }
+
+    fn contents(&self) -> Vec<Content> {
+        match self.token.kind {
+            TokenKind::TagName => {
+                self.registered_contents(false, format!("{{% {} %}}", self.text()))
+            }
+            TokenKind::FilterName => self.registered_contents(true, format!("|{}", self.text())),
+            TokenKind::String => self.literal_contents(),
+            TokenKind::Variable | TokenKind::Attribute => self.name_contents(),
+            _ => Vec::new(),
+        }
+    }
+
+    /// a tag or a filter: either one django ships or one the project registers,
+    /// and in both cases the answer is what it is documented to do
+    fn registered_contents(&self, filter: bool, written: String) -> Vec<Content> {
+        let name = self.text();
+        let header = Content::Code {
+            language: DJANGO,
+            text: written,
+        };
+
+        let builtin = if filter {
+            builtins::filter(name).map(|filter| (filter.documentation, filter.library))
+        } else {
+            builtins::tag(name).map(|tag| (tag.documentation, tag.library))
+        };
+
+        if let Some((documented, library)) = builtin {
+            return [header]
+                .into_iter()
+                .chain(documentation(documented, library))
+                .collect();
+        }
+
+        let registered = project::registrations(self.db, self.db.project())
+            .iter()
+            .find(|registration| {
+                (registration.kind == RegistrationKind::Filter) == filter
+                    && registration.name == name
+            });
+
+        let Some(registration) = registered else {
+            return Vec::new();
+        };
+
+        [header]
+            .into_iter()
+            .chain(documentation(
+                registration.documentation.as_deref().unwrap_or_default(),
+                Some(&registration.library),
+            ))
+            .collect()
+    }
+
+    /// what a string argument names, which depends on the tag it sits in
+    fn literal_contents(&self) -> Vec<Content> {
+        let value = string_contents(self.source, self.token.range);
+
+        match self.tag {
+            "extends" | "include" => {
+                let Some(reference) = self
+                    .index
+                    .extends()
+                    .into_iter()
+                    .chain(self.index.includes())
+                    .find(|reference| reference.range == value)
+                else {
+                    return Vec::new();
+                };
+
+                match project::resolve_template(self.db, &reference.name) {
+                    Some(target) => vec![Content::Text(format!(
+                        "template `{}`",
+                        target.path(self.db)
+                    ))],
+                    None => Vec::new(),
+                }
+            }
+            "url" => {
+                let name = &self.source[value];
+                project::url_names(self.db, self.db.project())
+                    .iter()
+                    .filter(|url| url.name == name)
+                    .filter_map(|url| url.route.as_deref())
+                    .map(|route| Content::Text(format!("route `{route}`")))
+                    .collect()
+            }
+            _ => Vec::new(),
+        }
+    }
+
+    /// what a bare name is, which again depends on the tag it sits in
+    fn name_contents(&self) -> Vec<Content> {
+        match self.tag {
+            "block" | "partialdef" => self.declaration_contents(),
+            "partial" => self.partial_contents(),
+            _ => self.path_contents(),
+        }
+    }
+
+    /// a `{% block %}` or a `{% partialdef %}` declares the name it writes
+    fn declaration_contents(&self) -> Vec<Content> {
+        let block = self.tag == "block";
+        let definitions = if block {
+            self.index.blocks()
+        } else {
+            self.index.partials()
+        };
+
+        let Some(definition) = definitions
+            .iter()
+            .find(|definition| definition.name_range == self.token.range)
+        else {
+            return Vec::new();
+        };
+
+        let header = Content::Code {
+            language: DJANGO,
+            text: format!("{{% {} {} %}}", self.tag, definition.name),
+        };
+
+        if !block {
+            return vec![
+                header,
+                Content::Text(format!(
+                    "a fragment `{{% partial {} %}}` renders",
+                    definition.name
+                )),
+            ];
+        }
+
+        // a block in a child template is an override, and which template it
+        // overrides is the thing worth saying about it
+        let overridden = super::ancestors(self.db, self.file, self.index)
+            .into_iter()
+            .find(|(_, ancestor)| {
+                ancestor
+                    .blocks()
+                    .iter()
+                    .any(|candidate| candidate.name == definition.name)
+            });
+
+        let text = match overridden {
+            Some((ancestor, _)) => format!("overrides the block in `{}`", self.label(ancestor)),
+            None => "a block a child template can override".to_string(),
+        };
+
+        vec![header, Content::Text(text)]
+    }
+
+    /// a `{% partial %}` renders a fragment this template or a parent declares
+    fn partial_contents(&self) -> Vec<Content> {
+        let name = self.text();
+
+        let declaring = std::iter::once((self.file, self.index))
+            .chain(super::ancestors(self.db, self.file, self.index))
+            .find(|(_, index)| index.partials().iter().any(|partial| partial.name == name));
+
+        let Some((declaring, _)) = declaring else {
+            return Vec::new();
+        };
+
+        vec![
+            Content::Code {
+                language: DJANGO,
+                text: format!("{{% partialdef {name} %}}"),
+            },
+            Content::Text(format!(
+                "a fragment declared in `{}`",
+                self.label(declaring)
+            )),
+        ]
+    }
+
+    /// the type of the path the name ends
+    fn path_contents(&self) -> Vec<Content> {
+        let segments = path_up_to(self.source, self.tokens, self.token, true);
+
+        if let Some(ty) = resolve::path_type(
+            self.db,
+            self.file,
+            self.index,
+            self.source,
+            self.offset,
+            &segments,
+        ) {
+            return vec![Content::Code {
+                language: "python",
+                text: format!("{}: {}", self.text(), ty.display(self.db)),
+            }];
+        }
+
+        // a name nothing gives a type to is still worth placing: the alternative
+        // is a hover that says nothing at all about a name the template knows
+        let [root] = segments[..] else {
+            return Vec::new();
+        };
+        if root != self.text() {
+            return Vec::new();
+        }
+
+        match resolve::resolve_root(self.db, self.file, self.index, self.offset, root) {
+            Some(Origin::Binding(_)) => vec![Content::Text("bound by this template".to_string())],
+            Some(Origin::Context(_)) => {
+                vec![Content::Text("from the view's context".to_string())]
+            }
+            None => Vec::new(),
+        }
+    }
+
+    /// how a template reads in prose: the name the loader knows it by, and its
+    /// path when it is not under a template root at all
+    fn label(&self, file: File) -> String {
+        resolve::template_name(self.db, file).unwrap_or_else(|| file.path(self.db).to_string())
+    }
+}
+
+/// a documentation section, with the `{% load %}` its name needs
+fn documentation(text: &str, library: Option<&str>) -> Option<Content> {
+    match library {
+        Some(library) => Some(Content::Text(format!(
+            "{text}\n\nrequires `{{% load {library} %}}`"
+        ))),
+        None if text.is_empty() => None,
+        None => Some(Content::Text(text.to_string())),
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use crate::django_template::tests::TemplateTest;
+
+    /// the same small django project the completion and goto tests use
+    fn project(template: &str) -> TemplateTest {
+        TemplateTest::new(&[
+            (
+                "blog/models.py",
+                "
+                class Author:
+                    name: str
+
+                class Book:
+                    title: str
+                    author: Author
+                ",
+            ),
+            (
+                "blog/views.py",
+                "
+                from blog.models import Book
+
+                def post(request):
+                    return render(request, 'blog/post.html', {'book': Book()})
+                ",
+            ),
+            (
+                "blog/urls.py",
+                "
+                app_name = 'blog'
+
+                urlpatterns = [path('books/', index, name='index')]
+                ",
+            ),
+            (
+                "blog/templatetags/blog_extras.py",
+                "
+                from django import template
+
+                register = template.Library()
+
+                @register.filter
+                def shout(value):
+                    'shouts it.'
+                    return value
+                ",
+            ),
+            (
+                "blog/templates/blog/base.html",
+                "{% block content %}{% endblock %}",
+            ),
+            ("blog/templates/blog/post.html", template),
+        ])
+    }
+
+    #[test]
+    fn a_context_variable_hovers_as_its_type() {
+        assert_eq!(
+            project("{{ bo<CURSOR>ok }}").hover(),
+            "```python\nbook: Book\n```"
+        );
+    }
+
+    #[test]
+    fn an_attribute_hovers_as_its_type() {
+        assert_eq!(
+            project("{{ book.ti<CURSOR>tle }}").hover(),
+            "```python\ntitle: str\n```"
+        );
+    }
+
+    #[test]
+    fn a_nested_attribute_hovers_as_its_type() {
+        assert_eq!(
+            project("{{ book.author.na<CURSOR>me }}").hover(),
+            "```python\nname: str\n```"
+        );
+    }
+
+    #[test]
+    fn a_name_with_no_type_still_says_where_it_comes_from() {
+        assert_eq!(
+            project("{% for entry in shelf %}{{ ent<CURSOR>ry }}{% endfor %}").hover(),
+            "bound by this template"
+        );
+    }
+
+    #[test]
+    fn a_loop_variable_hovers_as_the_element_type() {
+        let test = TemplateTest::new(&[
+            (
+                "blog/models.py",
+                "
+                class Chapter:
+                    title: str
+
+                class Book:
+                    chapters: list[Chapter]
+                ",
+            ),
+            (
+                "blog/views.py",
+                "
+                from blog.models import Book
+
+                def post(request):
+                    return render(request, 'blog/post.html', {'book': Book()})
+                ",
+            ),
+            (
+                "blog/templates/blog/post.html",
+                "{% for chapter in book.chapters %}{{ chap<CURSOR>ter }}{% endfor %}",
+            ),
+        ]);
+
+        assert_eq!(test.hover(), "```python\nchapter: Chapter\n```");
+    }
+
+    #[test]
+    fn a_builtin_filter_hovers_as_its_documentation() {
+        let hover = project("{{ book.title|up<CURSOR>per }}").hover();
+        assert!(
+            hover.starts_with("```django-html\n|upper\n```"),
+            "got {hover}"
+        );
+        assert!(hover.contains("upper-case"), "got {hover}");
+    }
+
+    #[test]
+    fn a_project_filter_hovers_as_its_docstring() {
+        assert_eq!(
+            project("{{ book.title|sh<CURSOR>out }}").hover(),
+            "```django-html\n|shout\n```\n---\nshouts it.\n\nrequires `{% load blog_extras %}`"
+        );
+    }
+
+    #[test]
+    fn a_builtin_tag_hovers_as_its_documentation() {
+        let hover = project("{% for<CURSOR> book in books %}{% endfor %}").hover();
+        assert!(
+            hover.starts_with("```django-html\n{% for %}\n```"),
+            "got {hover}"
+        );
+    }
+
+    #[test]
+    fn a_tag_from_a_library_says_what_to_load() {
+        let hover = project("{% st<CURSOR>atic 'a.css' %}").hover();
+        assert!(
+            hover.contains("requires `{% load static %}`"),
+            "got {hover}"
+        );
+    }
+
+    #[test]
+    fn an_unknown_tag_hovers_as_nothing() {
+        assert_eq!(project("{% myst<CURSOR>ery %}").hover(), "");
+    }
+
+    #[test]
+    fn extends_hovers_as_the_resolved_path() {
+        assert_eq!(
+            project("{% extends 'blog/b<CURSOR>ase.html' %}").hover(),
+            "template `/blog/templates/blog/base.html`"
+        );
+    }
+
+    #[test]
+    fn a_url_hovers_as_its_route() {
+        assert_eq!(
+            project("{% url 'blog:in<CURSOR>dex' %}").hover(),
+            "route `books/`"
+        );
+    }
+
+    #[test]
+    fn a_block_in_a_child_says_what_it_overrides() {
+        assert_eq!(
+            project("{% extends 'blog/base.html' %}{% block con<CURSOR>tent %}{% endblock %}")
+                .hover(),
+            "```django-html\n{% block content %}\n```\n---\noverrides the block in `blog/base.html`"
+        );
+    }
+
+    #[test]
+    fn a_block_with_no_parent_says_it_can_be_overridden() {
+        assert_eq!(
+            project("{% block con<CURSOR>tent %}{% endblock %}").hover(),
+            "```django-html\n{% block content %}\n```\n---\na block a child template can override"
+        );
+    }
+
+    #[test]
+    fn a_partialdef_says_how_it_is_rendered() {
+        assert_eq!(
+            project("{% partialdef ca<CURSOR>rd %}x{% endpartialdef %}").hover(),
+            "```django-html\n{% partialdef card %}\n```\n---\na fragment `{% partial card %}` renders"
+        );
+    }
+
+    #[test]
+    fn a_partial_says_where_it_is_declared() {
+        assert_eq!(
+            project("{% partialdef card %}x{% endpartialdef %}{% partial ca<CURSOR>rd %}").hover(),
+            "```django-html\n{% partialdef card %}\n```\n---\na fragment declared in `blog/post.html`"
+        );
+    }
+
+    #[test]
+    fn a_comment_hovers_as_nothing() {
+        assert_eq!(project("{# bo<CURSOR>ok #}").hover(), "");
+    }
+
+    #[test]
+    fn markup_outside_a_construct_hovers_as_nothing() {
+        assert_eq!(project("<p<CURSOR>>a</p>").hover(), "");
+    }
+}
diff --git a/crates/ty_ide/src/django_template/index.rs b/crates/ty_ide/src/django_template/index.rs
index 730565ebcc..9d072a2b61 100644
--- a/crates/ty_ide/src/django_template/index.rs
+++ b/crates/ty_ide/src/django_template/index.rs
@@ -163,6 +163,11 @@ impl TemplateIndex {
             .last()
     }
 
+    /// every block a pair of tags spans, in source order
+    pub(crate) fn spans(&self) -> &[Block] {
+        &self.spans
+    }
+
     /// the block tags still open at `offset`, innermost first
     ///
     /// this is what tells a completion inside `{% for %}…{% |` that the tag it
diff --git a/crates/ty_ide/src/django_template/project.rs b/crates/ty_ide/src/django_template/project.rs
index 0645c61979..8655b6282d 100644
--- a/crates/ty_ide/src/django_template/project.rs
+++ b/crates/ty_ide/src/django_template/project.rs
@@ -21,9 +21,13 @@ use ruff_db::source::source_text;
 use ruff_db::system::walk_directory::WalkState;
 use ruff_db::system::{FileType, SystemPath, SystemPathBuf};
 use ruff_python_ast::visitor::{Visitor, walk_expr, walk_stmt};
-use ruff_python_ast::{self as ast, Expr, Stmt};
+use ruff_python_ast::{self as ast, AnyNodeRef, Expr, Stmt};
 use ruff_text_size::{Ranged, TextRange};
 use ty_project::{Db, Project};
+use ty_python_semantic::SemanticModel;
+use ty_python_semantic::types::ide_support::{
+    ImportAliasResolution, definitions_for_attribute, definitions_for_name,
+};
 
 /// the directory name django's app-directories template loader looks in
 const TEMPLATE_DIRECTORY: &str = "templates";
@@ -35,10 +39,19 @@ const STATIC_DIRECTORY: &str = "static";
 const TEMPLATETAGS_PACKAGE: &str = "templatetags";
 
 /// the functions that render a named template with a context
-const CONTEXT_CALLEES: &[&str] = &["render", "TemplateResponse"];
+pub(crate) const CONTEXT_CALLEES: &[&str] = &["render", "TemplateResponse"];
 
 /// the class attribute a generic view names its template with
-const TEMPLATE_NAME_ATTRIBUTE: &str = "template_name";
+pub(crate) const TEMPLATE_NAME_ATTRIBUTE: &str = "template_name";
+
+/// the functions that resolve a route to its url by name
+pub(crate) const REVERSE_CALLEES: &[&str] = &["reverse", "reverse_lazy"];
+
+/// the function that redirects to a route named the same way
+///
+/// it is kept apart from [`REVERSE_CALLEES`] because it accepts a model or a url
+/// path just as happily as a route name, and so cannot be read as one on sight.
+pub(crate) const REDIRECT_CALLEE: &str = "redirect";
 
 /// the functions that give a route a reversible name
 const URL_CALLEES: &[&str] = &["path", "re_path", "url"];
@@ -46,6 +59,27 @@ const URL_CALLEES: &[&str] = &["path", "re_path", "url"];
 /// the keyword those functions take the name by
 const URL_NAME_KEYWORD: &str = "name";
 
+/// the method a rest framework router routes a viewset with
+const ROUTER_REGISTER_METHOD: &str = "register";
+
+/// the keyword a registration names its generated routes by
+const ROUTER_BASENAME_KEYWORD: &str = "basename";
+
+/// the routes a router gives every registered viewset
+const ROUTER_ROUTE_SUFFIXES: &[&str] = &["list", "detail"];
+
+/// the decorator that gives one viewset method a route of its own
+const ACTION_DECORATOR: &str = "action";
+
+/// the keyword an action names its route by
+const ACTION_URL_NAME_KEYWORD: &str = "url_name";
+
+/// the attribute a viewset's fallback basename is derived from
+const VIEWSET_QUERYSET_ATTRIBUTE: &str = "queryset";
+
+/// the manager attribute a queryset reaches its model through
+const MODEL_MANAGER_ATTRIBUTE: &str = "objects";
+
 /// how deep below the project root a `templates`/`static` directory is looked for
 ///
 /// django's own layout puts them at `<project>/<app>/templates`, and a
@@ -472,8 +506,12 @@ fn mentions(db: &dyn Db, file: File, names: &[&str]) -> bool {
 /// the url names one module defines
 #[salsa::tracked(returns(ref), heap_size=ruff_memory_usage::heap_size)]
 fn url_names_in_file(db: &dyn Db, file: File) -> Box<[UrlName]> {
-    // a named route is a `path()`-like call carrying a `name=` keyword
-    if !mentions(db, file, URL_CALLEES) || !mentions(db, file, &[URL_NAME_KEYWORD]) {
+    // a named route is a `path()`-like call carrying a `name=` keyword, or a
+    // rest framework router registration. the viewset a registration names is
+    // read through its definition rather than out of this file, so only the
+    // `register` call itself has to be spelled here for the scan to find one
+    let names_a_route = mentions(db, file, URL_CALLEES) && mentions(db, file, &[URL_NAME_KEYWORD]);
+    if !names_a_route && !mentions(db, file, &[ROUTER_REGISTER_METHOD]) {
         return Box::default();
     }
 
@@ -491,6 +529,7 @@ fn url_names_in_file(db: &dyn Db, file: File) -> Box<[UrlName]> {
     });
 
     let mut visitor = UrlVisitor {
+        db,
         file,
         namespace,
         found: Vec::new(),
@@ -500,35 +539,246 @@ fn url_names_in_file(db: &dyn Db, file: File) -> Box<[UrlName]> {
     visitor.found.into_boxed_slice()
 }
 
-struct UrlVisitor {
+struct UrlVisitor<'db> {
+    db: &'db dyn Db,
     file: File,
     namespace: Option<CompactString>,
     found: Vec<UrlName>,
 }
 
-impl<'ast> Visitor<'ast> for UrlVisitor {
-    fn visit_expr(&mut self, expr: &'ast Expr) {
-        if let Expr::Call(call) = expr
-            && callee_name(&call.func).is_some_and(|callee| URL_CALLEES.contains(&callee.as_str()))
-            && let Some(keyword) = call.arguments.find_keyword(URL_NAME_KEYWORD)
-            && let Some(name) = string_literal(&keyword.value)
-        {
-            let name = match &self.namespace {
-                Some(namespace) => format!("{namespace}:{name}").to_compact_string(),
-                None => name,
+impl UrlVisitor<'_> {
+    /// record `name`, under the module's `app_name` if it has one
+    fn record(&mut self, name: &str, file: File, range: TextRange, route: Option<&str>) {
+        let name = match &self.namespace {
+            Some(namespace) => format!("{namespace}:{name}").to_compact_string(),
+            None => name.to_compact_string(),
+        };
+
+        self.found.push(UrlName {
+            name,
+            file,
+            range,
+            route: route.map(Box::from),
+        });
+    }
+
+    /// the name a `path()`-like call gives its route
+    fn path_call(&mut self, call: &ast::ExprCall) {
+        if !callee_name(&call.func).is_some_and(|callee| URL_CALLEES.contains(&callee.as_str())) {
+            return;
+        }
+        let Some(keyword) = call.arguments.find_keyword(URL_NAME_KEYWORD) else {
+            return;
+        };
+        let Some(name) = string_literal(&keyword.value) else {
+            return;
+        };
+
+        let route = call.arguments.args.first().and_then(string_literal);
+        self.record(&name, self.file, keyword.value.range(), route.as_deref());
+    }
+
+    /// the names a rest framework router's registration makes reversible
+    ///
+    /// `router.register(prefix, viewset, basename=…)` routes a whole viewset the
+    /// way `path()` routes one view, and django resolves the routes it generates
+    /// by name like any other. the router's class is deliberately not checked,
+    /// since a project's own `SimpleRouter` subclass registers identically; what
+    /// identifies a registration is the method name and the shape of its
+    /// arguments, a string prefix followed by the viewset.
+    fn router_registration(&mut self, call: &ast::ExprCall) {
+        let Expr::Attribute(method) = &*call.func else {
+            return;
+        };
+        if method.attr.as_str() != ROUTER_REGISTER_METHOD {
+            return;
+        }
+        let Some(prefix) = call.arguments.find_argument_value("prefix", 0) else {
+            return;
+        };
+        let Some(prefix) = string_literal(prefix) else {
+            return;
+        };
+        // the viewset is named either directly or through the module it lives in
+        let Some(viewset @ (Expr::Name(_) | Expr::Attribute(_))) =
+            call.arguments.find_argument_value("viewset", 1)
+        else {
+            return;
+        };
+
+        let given = call
+            .arguments
+            .find_argument_value(ROUTER_BASENAME_KEYWORD, 2)
+            .and_then(|given| Some((string_literal(given)?, given.range())));
+
+        // the viewset's own file answers both what the routes are called when the
+        // registration doesn't say and which actions add routes of their own. it
+        // is read as best it can be: a viewset out of reach costs the actions,
+        // never the names the registration already gives on its own
+        let described = self.viewset(viewset);
+
+        let (basename, anchor) = match given {
+            Some(given) => given,
+            // a registration whose basename can't be worked out names nothing:
+            // django would reverse something, but a wrong name is worse than a
+            // missing one
+            None => match described
+                .as_ref()
+                .and_then(|described| described.basename.clone())
+            {
+                Some(basename) => (basename, viewset.range()),
+                None => return,
+            },
+        };
+
+        for suffix in ROUTER_ROUTE_SUFFIXES {
+            self.record(
+                &format!("{basename}-{suffix}"),
+                self.file,
+                anchor,
+                Some(prefix.as_str()),
+            );
+        }
+
+        for action in described.iter().flat_map(|described| &described.actions) {
+            // an action's route is that method's, so that is where it leads
+            self.record(
+                &format!("{basename}-{}", action.url_name),
+                action.file,
+                action.range,
+                Some(prefix.as_str()),
+            );
+        }
+    }
+
+    /// what a registered viewset says about the routes it is given
+    ///
+    /// following the name to its class reads another module's ast from this
+    /// module's query, and that cross-file dependency is deliberate: it is what
+    /// makes an `@action` added to a viewset appear in a template's completions
+    /// without the url configuration being touched. it costs one file per
+    /// registration, which is why it is affordable.
+    fn viewset(&self, viewset: &Expr) -> Option<ViewSet> {
+        let db = self.db;
+        let model = SemanticModel::new(db, self.file);
+
+        let definitions = match viewset {
+            Expr::Name(name) => definitions_for_name(
+                &model,
+                name.id.as_str(),
+                AnyNodeRef::from(name),
+                ImportAliasResolution::ResolveAliases,
+            ),
+            Expr::Attribute(attribute) => definitions_for_attribute(&model, attribute),
+            _ => return None,
+        };
+
+        definitions.into_iter().find_map(|resolved| {
+            let definition = resolved.definition()?;
+            let file = definition.file(db);
+            let parsed = parsed_module(db, file).load(db);
+            let class = definition.kind(db).as_class()?.node(&parsed);
+
+            Some(ViewSet {
+                basename: default_basename(class),
+                actions: actions(class, file),
+            })
+        })
+    }
+}
+
+/// what a viewset class contributes to the routes registering it generates
+struct ViewSet {
+    /// the basename a registration that doesn't give one falls back to
+    basename: Option<CompactString>,
+    actions: Vec<Action>,
+}
+
+/// one `@action`-decorated method of a viewset
+struct Action {
+    url_name: CompactString,
+    file: File,
+    /// the decorated method's name, for navigation
+    range: TextRange,
+}
+
+/// the basename a viewset that isn't registered under one falls back to
+///
+/// the router takes it from `queryset.model`, lower-cased, and the model of a
+/// queryset is the class its manager is reached through. a queryset built any
+/// other way — from `get_queryset`, or through a manager under some other name —
+/// leaves the basename unknown, and an unknown basename names no route at all.
+fn default_basename(class: &ast::StmtClassDef) -> Option<CompactString> {
+    let (queryset, _) = class
+        .body
+        .iter()
+        .find_map(|statement| class_attribute(statement, VIEWSET_QUERYSET_ATTRIBUTE))?;
+
+    Some(managed_model(queryset)?.to_lowercase().to_compact_string())
+}
+
+/// the class a manager expression hangs off, so that `models.Book.objects.all()`
+/// is a `Book`
+fn managed_model(expr: &Expr) -> Option<CompactString> {
+    let mut current = expr;
+
+    loop {
+        match current {
+            Expr::Call(call) => current = &call.func,
+            Expr::Attribute(attribute) => {
+                if attribute.attr.as_str() == MODEL_MANAGER_ATTRIBUTE {
+                    return match &*attribute.value {
+                        Expr::Name(name) => Some(name.id.to_compact_string()),
+                        Expr::Attribute(owner) => Some(owner.attr.id.to_compact_string()),
+                        _ => None,
+                    };
+                }
+                current = &attribute.value;
+            }
+            _ => return None,
+        }
+    }
+}
+
+/// the extra routes a viewset's `@action` methods are given
+///
+/// an action that doesn't name its route takes the method's own name with its
+/// underscores turned into dashes, which is what django will have to reverse.
+fn actions(class: &ast::StmtClassDef, file: File) -> Vec<Action> {
+    class
+        .body
+        .iter()
+        .filter_map(|statement| {
+            let Stmt::FunctionDef(function) = statement else {
+                return None;
             };
+            let decorator = function.decorator_list.iter().find_map(|decorator| {
+                let Expr::Call(call) = &decorator.expression else {
+                    return None;
+                };
+                (callee_name(&call.func)? == ACTION_DECORATOR).then_some(call)
+            })?;
+
+            let url_name = decorator
+                .arguments
+                .find_keyword(ACTION_URL_NAME_KEYWORD)
+                .and_then(|keyword| string_literal(&keyword.value))
+                .unwrap_or_else(|| function.name.as_str().replace('_', "-").to_compact_string());
+
+            Some(Action {
+                url_name,
+                file,
+                range: function.name.range(),
+            })
+        })
+        .collect()
+}
 
-            self.found.push(UrlName {
-                name,
-                file: self.file,
-                range: keyword.value.range(),
-                route: call
-                    .arguments
-                    .args
-                    .first()
-                    .and_then(string_literal)
-                    .map(|route| Box::from(route.as_str())),
-            });
+impl<'ast> Visitor<'ast> for UrlVisitor<'_> {
+    fn visit_expr(&mut self, expr: &'ast Expr) {
+        if let Expr::Call(call) = expr {
+            self.path_call(call);
+            self.router_registration(call);
         }
 
         walk_expr(self, expr);
@@ -717,7 +967,7 @@ impl<'ast> Visitor<'ast> for ContextAssignmentVisitor<'_> {
 }
 
 /// the value and name range of a class-body assignment to `attribute`
-fn class_attribute<'ast>(
+pub(crate) fn class_attribute<'ast>(
     statement: &'ast Stmt,
     attribute: &str,
 ) -> Option<(&'ast Expr, TextRange)> {
@@ -740,7 +990,7 @@ fn class_attribute<'ast>(
 }
 
 /// the final segment of a callee, so that `render` and `shortcuts.render` are one
-fn callee_name(func: &Expr) -> Option<CompactString> {
+pub(crate) fn callee_name(func: &Expr) -> Option<CompactString> {
     match func {
         Expr::Name(name) => Some(name.id.to_compact_string()),
         Expr::Attribute(attribute) => Some(attribute.attr.id.to_compact_string()),
@@ -792,6 +1042,14 @@ mod tests {
         TemplateTest::new(&all)
     }
 
+    /// the names the project's url configuration defines, in the order found
+    fn names(test: &TemplateTest) -> Vec<String> {
+        url_names(&test.db, test.db.project())
+            .iter()
+            .map(|url| url.name.to_string())
+            .collect()
+    }
+
     /// the names a view puts in `template`'s context, in the order offered
     fn context(test: &TemplateTest, template: &str) -> Vec<String> {
         context_for_template(&test.db, template)
@@ -914,6 +1172,242 @@ mod tests {
         assert_eq!(names, ["legacy", "index"]);
     }
 
+    #[test]
+    fn a_router_registration_names_a_list_and_a_detail_route() {
+        let test = project(&[(
+            "app/urls.py",
+            "
+            class BookViewSet: ...
+
+            router = DefaultRouter()
+            router.register('books', BookViewSet, basename='book')
+
+            urlpatterns = router.urls
+            ",
+        )]);
+
+        assert_eq!(names(&test), ["book-list", "book-detail"]);
+    }
+
+    #[test]
+    fn an_action_that_does_not_name_its_route_takes_the_methods_own_name() {
+        let test = project(&[(
+            "app/urls.py",
+            "
+            class BookViewSet:
+                @action(detail=True)
+                def mark_read(self, request, pk=None): ...
+
+            router = DefaultRouter()
+            router.register('books', BookViewSet, basename='book')
+            ",
+        )]);
+
+        assert_eq!(
+            names(&test),
+            ["book-list", "book-detail", "book-mark-read"],
+            "an underscore of the method's name is a dash of the route's"
+        );
+    }
+
+    #[test]
+    fn an_action_may_name_its_route_itself() {
+        let test = project(&[(
+            "app/urls.py",
+            "
+            class BookViewSet:
+                @action(detail=True, url_name='read')
+                def mark_read(self, request, pk=None): ...
+
+            router = DefaultRouter()
+            router.register('books', BookViewSet, basename='book')
+            ",
+        )]);
+
+        assert_eq!(names(&test), ["book-list", "book-detail", "book-read"]);
+    }
+
+    #[test]
+    fn a_registration_without_a_basename_takes_the_viewsets_model() {
+        // the viewset is a module away, as a real project's is
+        let test = project(&[
+            (
+                "app/views.py",
+                "
+                from app.models import Book
+
+                class BookViewSet:
+                    queryset = Book.objects.all()
+                ",
+            ),
+            (
+                "app/urls.py",
+                "
+                from app.views import BookViewSet
+
+                router = DefaultRouter()
+                router.register('books', BookViewSet)
+                ",
+            ),
+        ]);
+
+        assert_eq!(names(&test), ["book-list", "book-detail"]);
+    }
+
+    #[test]
+    fn a_viewset_may_be_named_through_the_module_it_lives_in() {
+        let test = project(&[
+            (
+                "app/views.py",
+                "
+                class BookViewSet:
+                    @action(detail=True)
+                    def mark_read(self, request, pk=None): ...
+                ",
+            ),
+            (
+                "app/urls.py",
+                "
+                from app import views
+
+                router = DefaultRouter()
+                router.register('books', views.BookViewSet, basename='book')
+                ",
+            ),
+        ]);
+
+        assert_eq!(names(&test), ["book-list", "book-detail", "book-mark-read"]);
+    }
+
+    #[test]
+    fn a_viewset_named_through_its_module_still_answers_for_its_basename() {
+        let test = project(&[
+            (
+                "app/views.py",
+                "
+                class BookViewSet:
+                    queryset = Book.objects.all()
+                ",
+            ),
+            (
+                "app/urls.py",
+                "
+                from app import views
+
+                router = DefaultRouter()
+                router.register('books', views.BookViewSet)
+                ",
+            ),
+        ]);
+
+        assert_eq!(names(&test), ["book-list", "book-detail"]);
+    }
+
+    #[test]
+    fn a_basename_the_registration_gives_stands_without_the_viewset() {
+        // only the actions need the class; the registration names the rest by
+        // itself, and refusing them because a viewset is out of reach would lose
+        // routes django reverses perfectly well
+        let test = project(&[(
+            "app/urls.py",
+            "
+            from third_party import views
+
+            router = DefaultRouter()
+            router.register('books', views.BookViewSet, basename='book')
+            ",
+        )]);
+
+        assert_eq!(names(&test), ["book-list", "book-detail"]);
+    }
+
+    #[test]
+    fn a_registration_whose_basename_cannot_be_worked_out_names_nothing() {
+        let test = project(&[(
+            "app/urls.py",
+            "
+            class BookViewSet:
+                def get_queryset(self): ...
+
+            router = DefaultRouter()
+            router.register('books', BookViewSet)
+            ",
+        )]);
+
+        assert!(
+            names(&test).is_empty(),
+            "django reverses a name here, but guessing which is worse than offering none"
+        );
+    }
+
+    #[test]
+    fn a_router_registrations_names_are_namespaced_like_any_others() {
+        let test = project(&[(
+            "app/urls.py",
+            "
+            app_name = 'api'
+
+            class BookViewSet: ...
+
+            router = DefaultRouter()
+            router.register('books', BookViewSet, basename='book')
+            ",
+        )]);
+
+        assert_eq!(names(&test), ["api:book-list", "api:book-detail"]);
+    }
+
+    #[test]
+    fn registering_a_model_with_the_admin_is_not_a_route() {
+        // it is a `register` call on an object taking a class, and the only thing
+        // telling it apart from a router's is that its first argument is no prefix
+        let test = project(&[(
+            "app/admin.py",
+            "
+            class BookAdmin:
+                queryset = Book.objects.all()
+
+            admin.site.register(Book, BookAdmin)
+            ",
+        )]);
+
+        assert!(names(&test).is_empty());
+    }
+
+    #[test]
+    fn an_actions_name_leads_to_the_method_that_serves_it() {
+        let test = project(&[
+            (
+                "app/views.py",
+                "
+                class BookViewSet:
+                    @action(detail=True)
+                    def mark_read(self, request, pk=None): ...
+                ",
+            ),
+            (
+                "app/urls.py",
+                "
+                from app.views import BookViewSet
+
+                router = DefaultRouter()
+                router.register('books', BookViewSet, basename='book')
+                ",
+            ),
+        ]);
+
+        let action = url_names(&test.db, test.db.project())
+            .iter()
+            .find(|url| url.name == "book-mark-read")
+            .expect("the action's route to be named");
+
+        assert_eq!(action.file.path(&test.db).to_string(), "/app/views.py");
+        assert_eq!(
+            &ruff_db::source::source_text(&test.db, action.file)[action.range],
+            "mark_read"
+        );
+    }
+
     #[test]
     fn an_inclusion_tags_first_argument_is_a_template_rather_than_a_name() {
         let test = project(&[(
diff --git a/crates/ty_ide/src/django_template/python.rs b/crates/ty_ide/src/django_template/python.rs
new file mode 100644
index 0000000000..f222fa21fc
--- /dev/null
+++ b/crates/ty_ide/src/django_template/python.rs
@@ -0,0 +1,220 @@
+//! the django names a python module spells out as plain strings
+//!
+//! `render(request, "blog/post.html")` names a template and `reverse("blog:detail")`
+//! names a route, but to python both are ordinary strings: nothing about the
+//! literal itself says what it is. what says it is the position — which function
+//! is being called, and which of its arguments the literal is — so that is all
+//! that is read here, and a literal in no recognised position never reaches the
+//! project's indexes at all.
+
+use compact_str::CompactString;
+use ruff_db::files::{File, FileRange};
+use ruff_db::parsed::ParsedModuleRef;
+use ruff_python_ast::find_node::covering_node;
+use ruff_python_ast::token::TokenKind;
+use ruff_python_ast::{self as ast, AnyNodeRef};
+use ruff_text_size::{Ranged, TextRange, TextSize};
+use rustc_hash::FxHashSet;
+use ty_project::Db;
+
+use crate::completion::CompletionKind;
+use crate::{NavigationTarget, NavigationTargets, RangedValue};
+
+use super::project::{
+    self, CONTEXT_CALLEES, REDIRECT_CALLEE, REVERSE_CALLEES, TEMPLATE_NAME_ATTRIBUTE, callee_name,
+    class_attribute,
+};
+
+/// what a string literal in a python module names
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+enum Names {
+    /// a template, under the name its loader knows it by
+    Template,
+    /// a route of the project's url configuration
+    Route,
+}
+
+/// one django name offered for a python string literal
+pub(crate) struct StringCompletion {
+    pub(crate) name: CompactString,
+    pub(crate) kind: CompletionKind,
+    /// the literal's contents, which is what the suggestion replaces
+    ///
+    /// neither `blog/post.html` nor `blog:detail` is a word by any client's
+    /// definition of one, so the range cannot be left to the client to guess.
+    pub(crate) range: TextRange,
+}
+
+/// the django names the string literal the cursor is in could be spelling
+///
+/// `ancestors` walks outwards from the node under the cursor, as
+/// [`ruff_python_ast::find_node::CoveringNode::ancestors`] does.
+pub(crate) fn string_completions<'a>(
+    db: &dyn Db,
+    ancestors: impl Iterator<Item = AnyNodeRef<'a>>,
+) -> Vec<StringCompletion> {
+    let Some((string, names)) = named(ancestors) else {
+        return Vec::new();
+    };
+    let Some(range) = contents(string) else {
+        return Vec::new();
+    };
+
+    match names {
+        Names::Template => {
+            let mut seen = FxHashSet::default();
+
+            project::template_files(db, db.project())
+                .iter()
+                // two apps may both hold a `base.html`; django's loader resolves
+                // the name to whichever comes first, so it is offered once
+                .filter(|file| seen.insert(file.name.clone()))
+                .map(|file| StringCompletion {
+                    name: file.name.clone(),
+                    kind: CompletionKind::File,
+                    range,
+                })
+                .collect()
+        }
+        Names::Route => project::url_names(db, db.project())
+            .iter()
+            .map(|url| StringCompletion {
+                name: url.name.clone(),
+                kind: CompletionKind::Reference,
+                range,
+            })
+            .collect(),
+    }
+}
+
+/// where the django name the string literal at `offset` spells is defined
+pub(crate) fn string_definition(
+    db: &dyn Db,
+    file: File,
+    parsed: &ParsedModuleRef,
+    offset: TextSize,
+) -> Option<RangedValue<NavigationTargets>> {
+    // every goto request comes through here, and walking the tree for a position
+    // that is plainly not a string would be a cost the whole crate pays for django
+    if !parsed
+        .tokens()
+        .at_offset(offset)
+        .any(|token| token.kind() == TokenKind::String)
+    {
+        return None;
+    }
+
+    let covering = covering_node(parsed.syntax().into(), TextRange::empty(offset));
+    let (string, names) = named(covering.ancestors())?;
+    let range = contents(string)?;
+    let value = string.value.to_str();
+
+    let targets: NavigationTargets = match names {
+        Names::Template => NavigationTargets::from_iter([NavigationTarget::new(
+            project::resolve_template(db, value)?,
+            TextRange::default(),
+        )]),
+        Names::Route => project::url_names(db, db.project())
+            .iter()
+            .filter(|url| url.name == value)
+            .map(|url| NavigationTarget::new(url.file, url.range))
+            .collect(),
+    };
+
+    (!targets.is_empty()).then(|| RangedValue {
+        range: FileRange::new(file, range),
+        value: targets,
+    })
+}
+
+/// what the string literal among `ancestors` names, if its position names anything
+fn named<'a>(
+    ancestors: impl Iterator<Item = AnyNodeRef<'a>>,
+) -> Option<(&'a ast::ExprStringLiteral, Names)> {
+    let outwards: Vec<AnyNodeRef<'a>> = ancestors.collect();
+
+    // a literal's only children are the parts it is written in, so the search
+    // never reaches past the literal the cursor is actually in
+    let (index, string) = outwards
+        .iter()
+        .enumerate()
+        .find_map(|(index, node)| match node {
+            AnyNodeRef::ExprStringLiteral(string) => Some((index, *string)),
+            _ => None,
+        })?;
+
+    let mut enclosing = outwards[index + 1..]
+        .iter()
+        // an argument list and a keyword sit between a literal and the call that
+        // takes it, and neither says anything on its own
+        .skip_while(|node| matches!(node, AnyNodeRef::Arguments(_) | AnyNodeRef::Keyword(_)));
+
+    let names = match enclosing.next()? {
+        AnyNodeRef::ExprCall(call) => argument(call, string)?,
+        AnyNodeRef::StmtAssign(_) | AnyNodeRef::StmtAnnAssign(_) => {
+            // `template_name = "…"` names a template where django reads one,
+            // which is the body of a view class
+            let AnyNodeRef::StmtClassDef(class) = enclosing.next()? else {
+                return None;
+            };
+            let names_a_template = class
+                .body
+                .iter()
+                .filter_map(|statement| class_attribute(statement, TEMPLATE_NAME_ATTRIBUTE))
+                .any(|(value, _)| value.range() == string.range());
+
+            names_a_template.then_some(Names::Template)?
+        }
+        _ => return None,
+    };
+
+    Some((string, names))
+}
+
+/// what the argument `string` of `call` names
+fn argument(call: &ast::ExprCall, string: &ast::ExprStringLiteral) -> Option<Names> {
+    let callee = callee_name(&call.func)?;
+    let positional = |index: usize| {
+        call.arguments
+            .args
+            .get(index)
+            .is_some_and(|argument| argument.range() == string.range())
+    };
+
+    if CONTEXT_CALLEES.contains(&callee.as_str()) {
+        // both take the request first and the template second, and both accept
+        // the template by keyword as well
+        let names_a_template = positional(1)
+            || call
+                .arguments
+                .find_keyword(TEMPLATE_NAME_ATTRIBUTE)
+                .is_some_and(|keyword| keyword.value.range() == string.range());
+
+        return names_a_template.then_some(Names::Template);
+    }
+
+    if REVERSE_CALLEES.contains(&callee.as_str()) {
+        return positional(0).then_some(Names::Route);
+    }
+
+    if callee == REDIRECT_CALLEE {
+        // a redirect takes a url or a model as readily as a route name. a name it
+        // doesn't recognise it simply doesn't answer for, but a string with a
+        // separator in it is a path beyond doubt and is refused outright
+        return (positional(0) && !string.value.to_str().contains('/')).then_some(Names::Route);
+    }
+
+    None
+}
+
+/// the range of a literal's contents, its prefix and quotes excluded
+///
+/// an implicitly concatenated literal is refused: a name written in two pieces
+/// is not one a suggestion could replace.
+fn contents(string: &ast::ExprStringLiteral) -> Option<TextRange> {
+    let [part] = string.value.as_slice() else {
+        return None;
+    };
+
+    Some(part.content_range())
+}
diff --git a/crates/ty_ide/src/django_template/symbols.rs b/crates/ty_ide/src/django_template/symbols.rs
new file mode 100644
index 0000000000..51669d7989
--- /dev/null
+++ b/crates/ty_ide/src/django_template/symbols.rs
@@ -0,0 +1,147 @@
+//! the outline of a django template
+//!
+//! what a template declares is its `{% block %}`s and its `{% partialdef %}`s:
+//! the names a child template can override and the fragments a `{% partial %}`
+//! can render. everything else in the file is markup, which the editor outlines
+//! far better than this could.
+
+use ruff_text_size::TextRange;
+
+use crate::{SymbolInfo, SymbolKind};
+
+use super::index::{Definition, TemplateIndex};
+
+/// one entry of a template's outline
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct TemplateSymbol {
+    pub name: String,
+    pub kind: SymbolKind,
+    /// the name as written in the opening tag
+    pub name_range: TextRange,
+    /// the opening tag's `{%` through the closing tag's `%}`
+    pub full_range: TextRange,
+    /// the declarations written inside this one
+    pub children: Vec<TemplateSymbol>,
+}
+
+impl TemplateSymbol {
+    /// this symbol on its own, for a client that wants a flat list
+    pub fn symbol_info(&self) -> SymbolInfo<'_> {
+        SymbolInfo {
+            name: self.name.as_str().into(),
+            kind: self.kind,
+            deprecated: false,
+            imported_from: None,
+            name_range: self.name_range,
+            full_range: self.full_range,
+        }
+    }
+}
+
+/// the declarations of `index`, nested as they are written
+pub(crate) fn document_symbols(index: &TemplateIndex) -> Vec<TemplateSymbol> {
+    let mut definitions: Vec<(SymbolKind, &Definition)> = index
+        .blocks()
+        .iter()
+        .map(|block| (SymbolKind::Module, block))
+        .chain(
+            index
+                .partials()
+                .iter()
+                .map(|partial| (SymbolKind::Function, partial)),
+        )
+        .collect();
+
+    // an enclosing declaration starts first, and starts at the same offset as
+    // nothing else, so ordering by start alone puts every parent before its
+    // children
+    definitions.sort_unstable_by_key(|(_, definition)| definition.full_range.start());
+
+    let mut roots = Vec::new();
+    let mut open: Vec<TemplateSymbol> = Vec::new();
+
+    for (kind, definition) in definitions {
+        while open
+            .last()
+            .is_some_and(|enclosing| !enclosing.full_range.contains_range(definition.full_range))
+        {
+            let Some(finished) = open.pop() else { break };
+            attach(finished, &mut open, &mut roots);
+        }
+
+        open.push(TemplateSymbol {
+            name: definition.name.to_string(),
+            kind,
+            name_range: definition.name_range,
+            full_range: definition.full_range,
+            children: Vec::new(),
+        });
+    }
+
+    while let Some(finished) = open.pop() {
+        attach(finished, &mut open, &mut roots);
+    }
+
+    roots
+}
+
+/// hand a finished symbol to the declaration enclosing it, or to the outline
+fn attach(symbol: TemplateSymbol, open: &mut [TemplateSymbol], roots: &mut Vec<TemplateSymbol>) {
+    match open.last_mut() {
+        Some(enclosing) => enclosing.children.push(symbol),
+        None => roots.push(symbol),
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use crate::django_template::tests::TemplateTest;
+
+    fn template(source: &str) -> TemplateTest {
+        TemplateTest::new(&[("blog/templates/blog/post.html", source)])
+    }
+
+    #[test]
+    fn a_template_outlines_its_blocks() {
+        let test = template(
+            "<CURSOR>{% block content %}a{% endblock %}\n{% block footer %}b{% endblock %}",
+        );
+        assert_eq!(test.symbols(), ["Module content", "Module footer"]);
+    }
+
+    #[test]
+    fn a_block_inside_a_block_nests_under_it() {
+        let test =
+            template("<CURSOR>{% block content %}{% block inner %}a{% endblock %}{% endblock %}");
+        assert_eq!(test.symbols(), ["Module content", "  Module inner"]);
+    }
+
+    #[test]
+    fn a_partialdef_is_outlined_too() {
+        let test = template("<CURSOR>{% partialdef card %}a{% endpartialdef %}");
+        assert_eq!(test.symbols(), ["Function card"]);
+    }
+
+    #[test]
+    fn a_partialdef_inside_a_block_nests_under_it() {
+        let test = template(
+            "<CURSOR>{% block content %}{% partialdef card %}a{% endpartialdef %}{% endblock %}",
+        );
+        assert_eq!(test.symbols(), ["Module content", "  Function card"]);
+    }
+
+    #[test]
+    fn a_block_that_was_never_closed_is_still_outlined() {
+        let test = template("<CURSOR>{% block content %}a");
+        assert_eq!(test.symbols(), ["Module content"]);
+    }
+
+    #[test]
+    fn a_template_with_no_declarations_has_no_outline() {
+        assert!(
+            template("<CURSOR><p>{{ book.title }}</p>")
+                .symbols()
+                .is_empty()
+        );
+    }
+}
diff --git a/crates/ty_ide/src/goto_definition.rs b/crates/ty_ide/src/goto_definition.rs
index eb9491c837..45019b208b 100644
--- a/crates/ty_ide/src/goto_definition.rs
+++ b/crates/ty_ide/src/goto_definition.rs
@@ -1,3 +1,4 @@
+use crate::django_template::django_string_definition;
 use crate::goto::find_goto_target;
 use crate::{Db, NavigationTargets, RangedValue};
 use ruff_db::files::{File, FileRange};
@@ -17,6 +18,13 @@ pub fn goto_definition(
     offset: TextSize,
 ) -> Option<RangedValue<NavigationTargets>> {
     let module = parsed_module(db, file).load(db);
+
+    // a template name and a url name are plain strings, so python's own answer
+    // for one is whatever `str` is — which is never where the user wanted to go
+    if let Some(named) = django_string_definition(db, file, &module, offset) {
+        return Some(named);
+    }
+
     let model = SemanticModel::new(db, file);
     let goto_target = find_goto_target(&model, &module, offset)?;
     let definition_targets = goto_target
@@ -2546,6 +2554,176 @@ class GenericFoo[T](Base):
         ");
     }
 
+    /// A django project whose `blog/views.py` carries the cursor.
+    fn django_test(views: &str) -> CursorTest {
+        CursorTest::builder()
+            .source("blog/templates/blog/post.html", "<h1>{{ post.title }}</h1>")
+            .source("blog/templates/blog/list.html", "<ul></ul>")
+            .source(
+                "blog/urls.py",
+                r#"
+app_name = "blog"
+
+urlpatterns = [
+    path("<int:pk>/", detail, name="detail"),
+]
+"#,
+            )
+            .source("blog/views.py", views)
+            .build()
+    }
+
+    #[test]
+    fn goto_definition_django_rendered_template() {
+        let test = django_test(
+            r#"
+def show(request):
+    return render(request, "blog/po<CURSOR>st.html")
+"#,
+        );
+
+        assert_snapshot!(test.goto_definition(), @r#"
+        info[goto-definition]: Go to definition
+         --> blog/views.py:3:29
+          |
+        3 |     return render(request, "blog/post.html")
+          |                             ^^^^^^^^^^^^^^ Clicking here
+          |
+        info: Found 1 definition
+         --> blog/templates/blog/post.html:1:1
+          |
+        1 | <h1>{{ post.title }}</h1>
+          | -
+          |
+        "#);
+    }
+
+    #[test]
+    fn goto_definition_django_template_of_a_template_response() {
+        let test = django_test(
+            r#"
+def show(request):
+    return TemplateResponse(request, "blog/li<CURSOR>st.html")
+"#,
+        );
+
+        assert_snapshot!(test.goto_definition(), @r#"
+        info[goto-definition]: Go to definition
+         --> blog/views.py:3:39
+          |
+        3 |     return TemplateResponse(request, "blog/list.html")
+          |                                       ^^^^^^^^^^^^^^ Clicking here
+          |
+        info: Found 1 definition
+         --> blog/templates/blog/list.html:1:1
+          |
+        1 | <ul></ul>
+          | -
+          |
+        "#);
+    }
+
+    #[test]
+    fn goto_definition_django_template_name_of_a_view_class() {
+        let test = django_test(
+            r#"
+class PostDetail(DetailView):
+    template_name = "blog/po<CURSOR>st.html"
+"#,
+        );
+
+        assert_snapshot!(test.goto_definition(), @r#"
+        info[goto-definition]: Go to definition
+         --> blog/views.py:3:22
+          |
+        3 |     template_name = "blog/post.html"
+          |                      ^^^^^^^^^^^^^^ Clicking here
+          |
+        info: Found 1 definition
+         --> blog/templates/blog/post.html:1:1
+          |
+        1 | <h1>{{ post.title }}</h1>
+          | -
+          |
+        "#);
+    }
+
+    #[test]
+    fn goto_definition_django_reversed_route() {
+        let test = django_test(
+            r#"
+def show(request):
+    return redirect(reverse("blog:de<CURSOR>tail"))
+"#,
+        );
+
+        assert_snapshot!(test.goto_definition(), @r#"
+        info[goto-definition]: Go to definition
+         --> blog/views.py:3:30
+          |
+        3 |     return redirect(reverse("blog:detail"))
+          |                              ^^^^^^^^^^^ Clicking here
+          |
+        info: Found 1 definition
+         --> blog/urls.py:5:36
+          |
+        5 |     path("<int:pk>/", detail, name="detail"),
+          |                                    --------
+          |
+        "#);
+    }
+
+    #[test]
+    fn goto_definition_django_redirected_route() {
+        let test = django_test(
+            r#"
+def show(request):
+    return redirect("blog:de<CURSOR>tail")
+"#,
+        );
+
+        assert_snapshot!(test.goto_definition(), @r#"
+        info[goto-definition]: Go to definition
+         --> blog/views.py:3:22
+          |
+        3 |     return redirect("blog:detail")
+          |                      ^^^^^^^^^^^ Clicking here
+          |
+        info: Found 1 definition
+         --> blog/urls.py:5:36
+          |
+        5 |     path("<int:pk>/", detail, name="detail"),
+          |                                    --------
+          |
+        "#);
+    }
+
+    #[test]
+    fn goto_definition_django_redirected_url_path() {
+        // a path is not a route name, and a redirect is the one call that takes
+        // both — so it leads nowhere django knows
+        let test = django_test(
+            r#"
+def show(request):
+    return redirect("/blog/<CURSOR>1/")
+"#,
+        );
+
+        assert_snapshot!(test.goto_definition(), @"No goto target found");
+    }
+
+    #[test]
+    fn goto_definition_django_template_that_is_not_there() {
+        let test = django_test(
+            r#"
+def show(request):
+    return render(request, "blog/mis<CURSOR>sing.html")
+"#,
+        );
+
+        assert_snapshot!(test.goto_definition(), @"No goto target found");
+    }
+
     impl CursorTest {
         fn goto_definition(&self) -> String {
             let Some(targets) = salsa::attach(&self.db, || {
diff --git a/crates/ty_ide/src/lib.rs b/crates/ty_ide/src/lib.rs
index 2ad97b70ab..0f2fe503ca 100644
--- a/crates/ty_ide/src/lib.rs
+++ b/crates/ty_ide/src/lib.rs
@@ -41,8 +41,10 @@ pub use completion::{
     CompletionSettings, completion,
 };
 pub use django_template::{
-    TemplateCompletion, TemplateEdit, django_template_completions, django_template_goto_definition,
-    django_template_semantic_tokens, is_django_template_path,
+    DisplayTemplateHover, TemplateCompletion, TemplateEdit, TemplateHover, TemplateSymbol,
+    django_template_completions, django_template_document_symbols, django_template_folding_ranges,
+    django_template_goto_definition, django_template_hover, django_template_semantic_tokens,
+    is_django_template_path,
 };
 pub use doc_highlights::document_highlights;
 pub use document_symbols::document_symbols;
diff --git a/crates/ty_server/src/server/api/requests/completion.rs b/crates/ty_server/src/server/api/requests/completion.rs
index db35fe622a..0eebecb98e 100644
--- a/crates/ty_server/src/server/api/requests/completion.rs
+++ b/crates/ty_server/src/server/api/requests/completion.rs
@@ -145,6 +145,18 @@ impl BackgroundDocumentRequestHandler for CompletionRequestHandler {
                     CompletionInsertTextFormat::PlainText => None,
                     CompletionInsertTextFormat::Snippet => Some(InsertTextFormat::Snippet),
                 };
+                // A completion that says what it replaces is one the client's own
+                // idea of the word under the cursor would get wrong, so the range
+                // is spelled out as an edit rather than left to be guessed.
+                let text_edit = comp.replace.and_then(|replace| {
+                    let range = replace
+                        .to_lsp_range(db, file, snapshot.encoding())?
+                        .local_range();
+                    Some(lsp_types::CompletionItemTextEdit::TextEdit(TextEdit {
+                        range,
+                        new_text: insert_text.clone().unwrap_or_else(|| label.clone()),
+                    }))
+                });
 
                 CompletionItem {
                     label,
@@ -154,6 +166,7 @@ impl BackgroundDocumentRequestHandler for CompletionRequestHandler {
                     label_details,
                     insert_text,
                     insert_text_format,
+                    text_edit,
                     additional_text_edits: import_edit.map(|edit| vec![edit]),
                     documentation,
                     ..Default::default()
diff --git a/crates/ty_server/src/server/api/requests/document_symbols.rs b/crates/ty_server/src/server/api/requests/document_symbols.rs
index 4b85aaf48e..2959422461 100644
--- a/crates/ty_server/src/server/api/requests/document_symbols.rs
+++ b/crates/ty_server/src/server/api/requests/document_symbols.rs
@@ -3,7 +3,10 @@ use std::borrow::Cow;
 use lsp_types::DocumentSymbolRequest;
 use lsp_types::{DocumentSymbol, DocumentSymbolParams, Uri};
 use ruff_db::files::File;
-use ty_ide::{HierarchicalSymbols, SymbolId, SymbolInfo, document_symbols};
+use ty_ide::{
+    HierarchicalSymbols, SymbolId, SymbolInfo, TemplateSymbol, django_template_document_symbols,
+    document_symbols,
+};
 use ty_project::ProjectDatabase;
 
 use crate::Db;
@@ -48,6 +51,15 @@ impl BackgroundDocumentRequestHandler for DocumentSymbolRequestHandler {
             .resolved_client_capabilities()
             .supports_hierarchical_document_symbols();
 
+        if snapshot.is_django_template() {
+            return Ok(template_symbols(
+                db,
+                file,
+                supports_hierarchical,
+                snapshot.encoding(),
+            ));
+        }
+
         let symbols = document_symbols(db, file);
         if symbols.is_empty() {
             return Ok(None);
@@ -90,6 +102,84 @@ impl BackgroundDocumentRequestHandler for DocumentSymbolRequestHandler {
 
 impl RetriableRequestHandler for DocumentSymbolRequestHandler {}
 
+/// the outline of a django template, in whichever shape the client understands
+fn template_symbols(
+    db: &ProjectDatabase,
+    file: File,
+    supports_hierarchical: bool,
+    encoding: PositionEncoding,
+) -> Option<lsp_types::DocumentSymbolResponse> {
+    let symbols = django_template_document_symbols(db, file);
+    if symbols.is_empty() {
+        return None;
+    }
+
+    if supports_hierarchical {
+        let lsp_symbols = symbols
+            .iter()
+            .filter_map(|symbol| convert_template_symbol(db, file, symbol, encoding))
+            .collect();
+
+        return Some(lsp_types::DocumentSymbolResponse::DocumentSymbolList(
+            lsp_symbols,
+        ));
+    }
+
+    let mut flattened = Vec::new();
+    flatten_template_symbols(&symbols, &mut flattened);
+
+    let lsp_symbols = flattened
+        .into_iter()
+        .filter_map(|symbol| convert_to_lsp_symbol_information(db, file, symbol, encoding))
+        .collect();
+
+    Some(lsp_types::DocumentSymbolResponse::SymbolInformationList(
+        lsp_symbols,
+    ))
+}
+
+fn convert_template_symbol(
+    db: &dyn Db,
+    file: File,
+    symbol: &TemplateSymbol,
+    encoding: PositionEncoding,
+) -> Option<DocumentSymbol> {
+    Some(DocumentSymbol {
+        name: symbol.name.clone(),
+        detail: None,
+        kind: convert_symbol_kind(symbol.kind),
+        tags: None,
+        #[allow(deprecated)]
+        deprecated: None,
+        range: symbol
+            .full_range
+            .to_lsp_range(db, file, encoding)?
+            .local_range(),
+        selection_range: symbol
+            .name_range
+            .to_lsp_range(db, file, encoding)?
+            .local_range(),
+        children: Some(
+            symbol
+                .children
+                .iter()
+                .filter_map(|child| convert_template_symbol(db, file, child, encoding))
+                .collect(),
+        ),
+    })
+}
+
+/// every symbol of the outline, each parent before what it encloses
+fn flatten_template_symbols<'a>(
+    symbols: &'a [TemplateSymbol],
+    flattened: &mut Vec<SymbolInfo<'a>>,
+) {
+    for symbol in symbols {
+        flattened.push(symbol.symbol_info());
+        flatten_template_symbols(&symbol.children, flattened);
+    }
+}
+
 fn convert_to_lsp_document_symbol(
     db: &dyn Db,
     file: File,
diff --git a/crates/ty_server/src/server/api/requests/folding_range.rs b/crates/ty_server/src/server/api/requests/folding_range.rs
index 21c06fb799..9ae0338ab6 100644
--- a/crates/ty_server/src/server/api/requests/folding_range.rs
+++ b/crates/ty_server/src/server/api/requests/folding_range.rs
@@ -4,7 +4,7 @@ use lsp_types::FoldingRangeRequest;
 use lsp_types::{FoldingRange, FoldingRangeKind, FoldingRangeParams, Uri};
 use ruff_db::source::source_text;
 use ruff_text_size::TextRange;
-use ty_ide::folding_ranges;
+use ty_ide::{django_template_folding_ranges, folding_ranges};
 use ty_project::ProjectDatabase;
 
 use crate::db::Db;
@@ -56,7 +56,13 @@ impl BackgroundDocumentRequestHandler for FoldingRangeRequestHandler {
             cell_range = cell_index.and_then(|index| notebook.cell_range(index));
         }
 
-        let results: Vec<_> = folding_ranges(db, file, cell_range)
+        let ranges = if snapshot.is_django_template() {
+            django_template_folding_ranges(db, file)
+        } else {
+            folding_ranges(db, file, cell_range)
+        };
+
+        let results: Vec<_> = ranges
             .into_iter()
             .filter_map(|folding_range| {
                 let lsp_range = folding_range
diff --git a/crates/ty_server/src/server/api/requests/hover.rs b/crates/ty_server/src/server/api/requests/hover.rs
index 81bbada3c4..70f09cb0d2 100644
--- a/crates/ty_server/src/server/api/requests/hover.rs
+++ b/crates/ty_server/src/server/api/requests/hover.rs
@@ -8,7 +8,7 @@ use crate::session::DocumentSnapshot;
 use crate::session::client::Client;
 use lsp_types::HoverRequest;
 use lsp_types::{HoverParams, MarkupContent, Uri};
-use ty_ide::{MarkupKind, hover};
+use ty_ide::{MarkupKind, django_template_hover, hover};
 use ty_project::ProjectDatabase;
 
 pub(crate) struct HoverRequestHandler;
@@ -48,10 +48,6 @@ impl BackgroundDocumentRequestHandler for HoverRequestHandler {
             return Ok(None);
         };
 
-        let Some(range_info) = hover(db, file, offset) else {
-            return Ok(None);
-        };
-
         let (markup_kind, lsp_markup_kind) = if snapshot
             .resolved_client_capabilities()
             .prefers_markdown_in_hover()
@@ -61,7 +57,25 @@ impl BackgroundDocumentRequestHandler for HoverRequestHandler {
             (MarkupKind::PlainText, lsp_types::MarkupKind::PlainText)
         };
 
-        let contents = range_info.display(db, markup_kind).to_string();
+        let hovered = if snapshot.is_django_template() {
+            django_template_hover(db, file, offset).map(|range_info| {
+                (
+                    range_info.display(markup_kind).to_string(),
+                    range_info.range,
+                )
+            })
+        } else {
+            hover(db, file, offset).map(|range_info| {
+                (
+                    range_info.display(db, markup_kind).to_string(),
+                    range_info.range,
+                )
+            })
+        };
+
+        let Some((contents, range)) = hovered else {
+            return Ok(None);
+        };
 
         Ok(Some(lsp_types::Hover {
             contents: MarkupContent {
@@ -69,8 +83,7 @@ impl BackgroundDocumentRequestHandler for HoverRequestHandler {
                 value: contents,
             }
             .into(),
-            range: range_info
-                .file_range()
+            range: range
                 .to_lsp_range(db, snapshot.encoding())
                 .map(|lsp_range| lsp_range.local_range()),
         }))
diff --git a/crates/ty_server/tests/e2e/django_templates.rs b/crates/ty_server/tests/e2e/django_templates.rs
index c90d1179db..90326ebba7 100644
--- a/crates/ty_server/tests/e2e/django_templates.rs
+++ b/crates/ty_server/tests/e2e/django_templates.rs
@@ -178,6 +178,73 @@ fn a_template_navigates_to_the_template_it_extends() -> Result<()> {
     Ok(())
 }
 
+#[test]
+fn a_template_hovers_a_context_variables_attribute_as_its_type() -> Result<()> {
+    let mut server = server("<p>{{ book.title }}</p>\n")?;
+
+    let hover = server
+        .hover_request(
+            SystemPath::new("src/blog/templates/blog/post.html"),
+            Position::new(0, 13),
+        )
+        .expect("a hover response");
+
+    let rendered = format!("{:?}", hover.contents);
+    assert!(rendered.contains("title: str"), "got {rendered}");
+
+    Ok(())
+}
+
+#[test]
+fn a_template_hovers_a_filter_as_its_documentation() -> Result<()> {
+    let mut server = server("<p>{{ book.title|upper }}</p>\n")?;
+
+    let hover = server
+        .hover_request(
+            SystemPath::new("src/blog/templates/blog/post.html"),
+            Position::new(0, 19),
+        )
+        .expect("a hover response");
+
+    let rendered = format!("{:?}", hover.contents);
+    assert!(rendered.contains("|upper"), "got {rendered}");
+
+    Ok(())
+}
+
+#[test]
+fn a_template_outlines_its_blocks() -> Result<()> {
+    let mut server =
+        server("{% block content %}\n{% block inner %}\na\n{% endblock %}\n{% endblock %}\n")?;
+    let uri = template_uri(&server);
+
+    let response = server
+        .document_symbol_request(&uri)
+        .expect("a document symbol response");
+
+    let rendered = format!("{response:?}");
+    assert!(rendered.contains("content"), "got {rendered}");
+    assert!(rendered.contains("inner"), "got {rendered}");
+
+    Ok(())
+}
+
+#[test]
+fn a_template_folds_its_block_tags() -> Result<()> {
+    let mut server = server("{% for book in books %}\n<p>{{ book.title }}</p>\n{% endfor %}\n")?;
+    let uri = template_uri(&server);
+
+    let ranges = server
+        .folding_range_request(&uri)
+        .expect("a folding range response");
+
+    assert_eq!(ranges.len(), 1, "got {ranges:?}");
+    assert_eq!(ranges[0].start_line, 0);
+    assert_eq!(ranges[0].end_line, 2);
+
+    Ok(())
+}
+
 #[test]
 fn a_template_created_during_the_session_is_offered_to_an_extends() -> Result<()> {
     // discovering templates means walking the file system, which salsa cannot
diff --git a/crates/ty_server/tests/e2e/main.rs b/crates/ty_server/tests/e2e/main.rs
index 55aea01c25..dcc8a2ef18 100644
--- a/crates/ty_server/tests/e2e/main.rs
+++ b/crates/ty_server/tests/e2e/main.rs
@@ -66,12 +66,13 @@ use lsp_types::{
     DidChangeWorkspaceFoldersParams, DidCloseTextDocumentNotification, DidCloseTextDocumentParams,
     DidOpenTextDocumentNotification, DidOpenTextDocumentParams, DidSaveTextDocumentNotification,
     DidSaveTextDocumentParams, DocumentDiagnosticParams, DocumentDiagnosticReport,
-    DocumentDiagnosticRequest, ExitNotification, FileEvent, FoldingRange, FoldingRangeParams,
-    Hover, HoverParams, HoverRequest, InitializeParams, InitializeRequest, InitializeResult,
-    InitializedNotification, InitializedParams, InlayHint, InlayHintClientCapabilities,
-    InlayHintParams, InlayHintRequest, LanguageKind, Notification, PartialResultParams, Position,
-    PrepareRenameRequest, PreviousResultId, PublishDiagnosticsClientCapabilities, Range, Request,
-    SemanticTokens, ShutdownRequest, SignatureHelp, SignatureHelpParams, SignatureHelpRequest,
+    DocumentDiagnosticRequest, DocumentSymbolParams, DocumentSymbolResponse, ExitNotification,
+    FileEvent, FoldingRange, FoldingRangeParams, Hover, HoverParams, HoverRequest,
+    InitializeParams, InitializeRequest, InitializeResult, InitializedNotification,
+    InitializedParams, InlayHint, InlayHintClientCapabilities, InlayHintParams, InlayHintRequest,
+    LanguageKind, Notification, PartialResultParams, Position, PrepareRenameRequest,
+    PreviousResultId, PublishDiagnosticsClientCapabilities, Range, Request, SemanticTokens,
+    ShutdownRequest, SignatureHelp, SignatureHelpParams, SignatureHelpRequest,
     SignatureHelpTriggerKind, TextDocumentClientCapabilities, TextDocumentContentChangeEvent,
     TextDocumentIdentifier, TextDocumentItem, TextDocumentPositionParams, Uri,
     VersionedTextDocumentIdentifier, WorkDoneProgressParams, WorkspaceClientCapabilities,
@@ -1060,6 +1061,15 @@ impl TestServer {
         )
     }
 
+    /// Sends a `textDocument/documentSymbol` request for the document at the given URI.
+    pub(crate) fn document_symbol_request(&mut self, uri: &Uri) -> Option<DocumentSymbolResponse> {
+        self.send_request_await::<lsp_types::DocumentSymbolRequest>(DocumentSymbolParams {
+            text_document: TextDocumentIdentifier { uri: uri.clone() },
+            work_done_progress_params: WorkDoneProgressParams::default(),
+            partial_result_params: PartialResultParams::default(),
+        })
+    }
+
     pub(crate) fn folding_range_request(&mut self, uri: &Uri) -> Option<Vec<FoldingRange>> {
         self.send_request_await::<lsp_types::FoldingRangeRequest>(FoldingRangeParams {
             text_document: TextDocumentIdentifier { uri: uri.clone() },
diff --git a/docs/basedpython/frameworks/django-templates.md b/docs/basedpython/frameworks/django-templates.md
index 217b5643e6..c67308b08d 100644
--- a/docs/basedpython/frameworks/django-templates.md
+++ b/docs/basedpython/frameworks/django-templates.md
@@ -52,6 +52,30 @@ the editor's own html grammar keeps the markup; the server adds what a grammar c
 - `{% block %}` and `{% partialdef %}` names read as the fragments they name, not as variables
 - `{% comment %}` bodies and `{# … #}` are comments; `{% verbatim %}` bodies are plain text
 
+### hover and outline
+
+hovering says what the thing under the caret is: a variable or a path segment as its type, a tag or a filter as its documentation and the `{% load %}` it needs, a `{% block %}` as the block it overrides, an `{% extends %}` as the file it resolves to, a `{% url %}` as its route pattern.
+
+a template's `{% block %}`s and `{% partialdef %}`s are its outline, nested as they nest, and every block tag folds.
+
+**no diagnostics.** templates are never type-checked — an unknown variable or a misspelled filter is not reported, it just doesn't complete.
+
+## the same names, written in python
+
+a template name in a `render()` and a route name in a `reverse()` are plain strings as far as python is concerned. the editor reads them as the names they are, so the same completions and the same navigation are there from the python side.
+
+| position                              | what is offered              | goes to                  |
+| ------------------------------------- | ---------------------------- | ------------------------ |
+| `render(request, '‸')`                | the project's template paths | that template            |
+| `TemplateResponse(request, '‸')`      | the project's template paths | that template            |
+| `template_name = '‸'` in a view class | the project's template paths | that template            |
+| `reverse('‸')`, `reverse_lazy('‸')`   | the project's route names    | whatever names the route |
+| `redirect('‸')`                       | the project's route names    | whatever names the route |
+
+the function is matched by its last segment, so `shortcuts.render` and `render` are one, and `render()` accepts its template by keyword as `template_name=` too.
+
+`redirect()` takes a url or a model as readily as a route name, so a string with a `/` in it is left alone entirely and a name the url configuration doesn't have leads nowhere.
+
 ## how a template's variables are found
 
 the chain runs from the template back to the type checker:
@@ -114,8 +138,6 @@ template directories, static directories and tag libraries are found by their co
 
 ## limitations
 
-**no diagnostics.** templates are never type-checked. an unknown variable or a misspelled filter is not reported — it just doesn't complete.
-
 **a `TEMPLATES` setting is not read.** template directories are found by name rather than from `settings.py`, so a `DIRS` entry pointing somewhere else is not picked up.
 
 **the context has to be written where it is passed.** the names are read out of the dict literal in the `render()` call or the view class, so a context built somewhere else and passed by name — `return render(request, "…", context)` — contributes nothing.
@@ -126,6 +148,10 @@ template directories, static directories and tag libraries are found by their co
 
 **`{% url %}` namespaces come from `app_name`.** a namespace given at the `include()` instead is not applied.
 
+**a route is named by a `path()` or by a rest framework router.** `router.register('books', BookViewSet, basename='book')` names `book-list` and `book-detail`, and each `@action` on the viewset names one more. a registration whose basename cannot be worked out — no `basename=` and no resolvable `queryset` — names nothing rather than guessing.
+
+**a name written in python has to be a literal.** the string in a `render()` or a `reverse()` is read as it is written, so a name built from an f-string, or held in a variable, is just a string.
+
 ## see also
 
 - [django support](django.md) — the type checker's understanding of models, fields and queries

From 3320d3fb9264f99cf2d311ec0645bb1c15b3eb6e Mon Sep 17 00:00:00 2001
From: KotlinIsland <65446343+kotlinisland@users.noreply.github.com>
Date: Sat, 8 Aug 2026 21:38:32 +1000
Subject: [PATCH 04/16] a project's settings, libraries and url tree, read
 rather than guessed

the three indexes that had to agree with django before any diagnostic could ship
honestly: `TEMPLATES`/`APP_DIRS`/`INSTALLED_APPS` from the settings module the
project actually names, the tag libraries it can `{% load %}`, and the url tree
walked for route names

each carries an is-authoritative predicate, so a project whose settings cannot be
read reports nothing rather than guessing
---
 crates/ty_ide/src/completion.rs               |    3 +
 crates/ty_ide/src/django_template.rs          |   71 +-
 .../ty_ide/src/django_template/completion.rs  |  222 +-
 crates/ty_ide/src/django_template/goto.rs     |   67 +-
 crates/ty_ide/src/django_template/project.rs  | 2480 ++++++++++++++++-
 .../src/django_template/semantic_tokens.rs    |  132 +-
 .../frameworks/django-templates.md            |   32 +-
 7 files changed, 2839 insertions(+), 168 deletions(-)

diff --git a/crates/ty_ide/src/completion.rs b/crates/ty_ide/src/completion.rs
index 31ccbd732b..85adbed100 100644
--- a/crates/ty_ide/src/completion.rs
+++ b/crates/ty_ide/src/completion.rs
@@ -8523,6 +8523,7 @@ def show(request):
         );
 
         assert_snapshot!(builder.build().snapshot(), @"
+        blog:api-root
         blog:book-detail
         blog:book-list
         blog:detail
@@ -8539,6 +8540,7 @@ url = urls.reverse_lazy("<CURSOR>")
         );
 
         assert_snapshot!(builder.build().snapshot(), @"
+        blog:api-root
         blog:book-detail
         blog:book-list
         blog:detail
@@ -8556,6 +8558,7 @@ def show(request):
         );
 
         assert_snapshot!(builder.build().snapshot(), @"
+        blog:api-root
         blog:book-detail
         blog:book-list
         blog:detail
diff --git a/crates/ty_ide/src/django_template.rs b/crates/ty_ide/src/django_template.rs
index a199c9db03..1d161c3fb7 100644
--- a/crates/ty_ide/src/django_template.rs
+++ b/crates/ty_ide/src/django_template.rs
@@ -97,6 +97,7 @@ pub fn django_template_semantic_tokens(
 ) -> SemanticTokens {
     let source = source_text(db, file);
     SemanticTokens::new(semantic_tokens::semantic_tokens(
+        db,
         template_index(db, file),
         source.as_str(),
         range,
@@ -180,12 +181,17 @@ pub fn django_template_completions(
 
 #[cfg(test)]
 pub(crate) mod tests {
-    use ruff_db::files::{File, system_path_to_file};
-    use ruff_db::system::{DbWithWritableSystem, SystemPath, SystemPathBuf};
+    use ruff_db::Db as _;
+    use ruff_db::files::{File, FileRootKind, system_path_to_file};
+    use ruff_db::system::{DbWithTestSystem, DbWithWritableSystem, SystemPath, SystemPathBuf};
     use ruff_python_ast::PythonVersion;
     use ruff_python_trivia::textwrap::dedent;
     use ruff_text_size::TextSize;
+    use ty_module_resolver::SearchPathSettings;
     use ty_project::{ProjectMetadata, TestDb};
+    use ty_python_core::platform::PythonPlatform;
+    use ty_python_core::program::{FallibleStrategy, Program, ProgramSettings};
+    use ty_python_semantic::PythonVersionWithSource;
 
     use crate::MarkupKind;
 
@@ -206,12 +212,64 @@ pub(crate) mod tests {
     impl TemplateTest {
         /// build a project from `(path, contents)` pairs
         pub(crate) fn new(sources: &[(&str, &str)]) -> Self {
-            const MARKER: &str = "<CURSOR>";
-
             let mut db = TestDb::new(ProjectMetadata::new("test", SystemPathBuf::from("/")));
             db.init_program_with_python_version(PythonVersion::latest_ty())
                 .unwrap();
 
+            Self::write(db, SystemPath::new("/"), sources)
+        }
+
+        /// the same, with `installed` written to a site-packages directory
+        ///
+        /// site-packages sits *outside* the project root, which is what makes
+        /// what is written there third-party rather than the project's own —
+        /// under the root it would be found by the first-party scans instead.
+        pub(crate) fn with_site_packages(
+            sources: &[(&str, &str)],
+            installed: &[(&str, &str)],
+        ) -> Self {
+            let root = SystemPathBuf::from("/src");
+            let site_packages = SystemPathBuf::from("/site-packages");
+
+            let mut db = TestDb::new(ProjectMetadata::new("test", root.clone()));
+
+            for (path, contents) in installed {
+                db.write_file(site_packages.join(path), dedent(contents).as_ref())
+                    .unwrap();
+            }
+            db.memory_file_system().create_directory_all(&root).unwrap();
+            db.memory_file_system()
+                .create_directory_all(&site_packages)
+                .unwrap();
+
+            let search_paths = SearchPathSettings {
+                src_roots: vec![root.clone()],
+                site_packages_paths: vec![site_packages.clone()],
+                ..SearchPathSettings::empty()
+            }
+            .to_search_paths(db.system(), db.vendored(), &FallibleStrategy)
+            .expect("valid search paths");
+
+            Program::from_settings(
+                &db,
+                ProgramSettings {
+                    python_version: PythonVersionWithSource::default(),
+                    python_platform: PythonPlatform::default(),
+                    search_paths,
+                },
+            );
+
+            db.files().try_add_root(&db, &root, FileRootKind::Project);
+            db.files()
+                .try_add_root(&db, &site_packages, FileRootKind::SearchPath);
+
+            Self::write(db, &root, sources)
+        }
+
+        /// write every source under `root`, taking the one `<CURSOR>` marker out
+        fn write(mut db: TestDb, root: &SystemPath, sources: &[(&str, &str)]) -> Self {
+            const MARKER: &str = "<CURSOR>";
+
             let mut cursor = None;
 
             for (path, contents) in sources {
@@ -226,8 +284,9 @@ pub(crate) mod tests {
                     None => (contents, None),
                 };
 
-                db.write_file(path, &contents).unwrap();
-                let file = system_path_to_file(&db, path).unwrap();
+                let path = root.join(path);
+                db.write_file(&path, &contents).unwrap();
+                let file = system_path_to_file(&db, &path).unwrap();
 
                 if let Some(offset) = offset {
                     assert!(cursor.is_none(), "more than one `<CURSOR>` marker");
diff --git a/crates/ty_ide/src/django_template/completion.rs b/crates/ty_ide/src/django_template/completion.rs
index d9ef6a0d96..d6b71ad9d6 100644
--- a/crates/ty_ide/src/django_template/completion.rs
+++ b/crates/ty_ide/src/django_template/completion.rs
@@ -23,7 +23,7 @@ use crate::completion::CompletionKind;
 use super::builtins;
 use super::index::{Block, TemplateIndex};
 use super::lexer::{Construct, ConstructKind, Token, TokenKind, string_contents};
-use super::project::{self, RegistrationKind};
+use super::project::{self, LibrarySource, Registration, RegistrationKind};
 use super::resolve;
 
 /// an edit a completion carries alongside the text it inserts
@@ -384,22 +384,27 @@ fn tag_names(
         }
     }
 
-    let loaded = loaded_libraries(index);
+    let loaded = loaded_libraries(db, index);
     let load_edit = |library: Option<&str>| load_edit_for(index, &loaded, library);
+    let registrations = project::registrations(db, db.project());
 
     for tag in builtins::TAGS {
+        let library = djangos_library(registrations, tag.name, false).or(tag.library);
+
         let mut completion =
             TemplateCompletion::new(tag.name, CompletionKind::Keyword, cursor.range)
                 .documentation(tag.documentation);
-        if let Some(library) = tag.library {
+        if let Some(library) = library {
             completion = completion.detail(format!("{{% load {library} %}}"));
         }
-        completion.additional_edit = load_edit(tag.library);
+        completion.additional_edit = load_edit(library);
         completions.push(completion);
     }
 
-    for registration in project::registrations(db, db.project()) {
-        if registration.kind == RegistrationKind::Filter {
+    for registration in registrations {
+        if registration.kind == RegistrationKind::Filter
+            || offered_by_the_table(registration, false)
+        {
             continue;
         }
 
@@ -425,27 +430,66 @@ fn opening_tag(source: &str, block: &Block) -> String {
     source[block.open_range].trim().to_string()
 }
 
+/// the library the project's own django registers `name` under, when it does
+///
+/// the builtin table was written against one version of django, and a name can
+/// move between libraries or arrive in one from release to release. where the
+/// project's own django can be read, it is that django which decides. a tag the
+/// *project* happens to name after a builtin is not django's and says nothing.
+fn djangos_library<'a>(
+    registrations: &'a [Registration],
+    name: &str,
+    filter: bool,
+) -> Option<&'a str> {
+    registrations
+        .iter()
+        .find(|registration| {
+            registration.django
+                && registration.name == name
+                && (registration.kind == RegistrationKind::Filter) == filter
+        })
+        .map(|registration| registration.library.as_str())
+}
+
+/// whether the builtin table already offers this registration
+///
+/// django's own libraries are discovered *and* tabulated, and the table's entry
+/// is the richer of the two — it carries the documentation, and for a tag the
+/// block structure as well — so it is the one offered.
+fn offered_by_the_table(registration: &Registration, filter: bool) -> bool {
+    registration.django
+        && if filter {
+            builtins::filter(&registration.name).is_some()
+        } else {
+            builtins::tag(&registration.name).is_some()
+        }
+}
+
 fn filter_names(
     db: &dyn Db,
     index: &TemplateIndex,
     cursor: &Cursor<'_>,
 ) -> Vec<TemplateCompletion> {
-    let loaded = loaded_libraries(index);
+    let loaded = loaded_libraries(db, index);
     let mut completions = Vec::new();
+    let registrations = project::registrations(db, db.project());
 
     for filter in builtins::FILTERS {
+        let library = djangos_library(registrations, filter.name, true).or(filter.library);
+
         let mut completion =
             TemplateCompletion::new(filter.name, CompletionKind::Function, cursor.range)
                 .documentation(filter.documentation);
-        if let Some(library) = filter.library {
+        if let Some(library) = library {
             completion = completion.detail(format!("{{% load {library} %}}"));
         }
-        completion.additional_edit = load_edit_for(index, &loaded, filter.library);
+        completion.additional_edit = load_edit_for(index, &loaded, library);
         completions.push(completion);
     }
 
-    for registration in project::registrations(db, db.project()) {
-        if registration.kind != RegistrationKind::Filter {
+    for registration in registrations {
+        if registration.kind != RegistrationKind::Filter || offered_by_the_table(registration, true)
+        {
             continue;
         }
 
@@ -578,7 +622,7 @@ fn url_names(db: &dyn Db, cursor: &Cursor<'_>) -> Vec<TemplateCompletion> {
 }
 
 fn libraries(db: &dyn Db, index: &TemplateIndex, cursor: &Cursor<'_>) -> Vec<TemplateCompletion> {
-    let loaded = loaded_libraries(index);
+    let loaded = loaded_libraries(db, index);
     let mut completions = Vec::new();
     let mut seen = FxHashSet::default();
 
@@ -593,17 +637,17 @@ fn libraries(db: &dyn Db, index: &TemplateIndex, cursor: &Cursor<'_>) -> Vec<Tem
         );
     }
 
-    for registration in project::registrations(db, db.project()) {
-        if loaded.contains(&registration.library) || !seen.insert(registration.library.clone()) {
+    for library in project::tag_libraries(db, db.project()) {
+        if loaded.contains(&library.name) || !seen.insert(library.name.clone()) {
             continue;
         }
         completions.push(
-            TemplateCompletion::new(
-                registration.library.as_str(),
-                CompletionKind::Module,
-                cursor.range,
-            )
-            .detail("this project"),
+            TemplateCompletion::new(library.name.as_str(), CompletionKind::Module, cursor.range)
+                .detail(match library.source {
+                    LibrarySource::Django => "django",
+                    LibrarySource::Project => "this project",
+                    LibrarySource::Installed => "installed",
+                }),
         );
     }
 
@@ -685,12 +729,22 @@ fn inherited(
         .collect()
 }
 
-/// the libraries the template has already `{% load %}`ed
-fn loaded_libraries(index: &TemplateIndex) -> FxHashSet<CompactString> {
+/// the libraries the template does not have to `{% load %}`
+///
+/// the ones it has loaded already, and the ones the settings load into every
+/// template — a `{% load %}` for one of those is not wrong, but it is noise, so
+/// neither is one suggested.
+fn loaded_libraries(db: &dyn Db, index: &TemplateIndex) -> FxHashSet<CompactString> {
     index
         .loads()
         .iter()
         .map(|load| load.library.clone())
+        .chain(
+            project::tag_libraries(db, db.project())
+                .iter()
+                .filter(|library| library.always_loaded)
+                .map(|library| library.name.clone()),
+        )
         .collect()
 }
 
@@ -811,6 +865,70 @@ mod tests {
         ])
     }
 
+    /// the same project with a mock django installed beside it, the `humanize`
+    /// contrib app among its `INSTALLED_APPS`
+    ///
+    /// `options` goes into the one template engine, which is how a project asks
+    /// for a library to be loaded into every template.
+    fn with_humanize(template: &str, options: &str) -> TemplateTest {
+        let settings = format!(
+            "
+            INSTALLED_APPS = ['django.contrib.humanize', 'blog']
+
+            TEMPLATES = [{{'APP_DIRS': True, 'OPTIONS': {{{options}}}}}]
+            "
+        );
+
+        TemplateTest::with_site_packages(
+            &[
+                (
+                    "manage.py",
+                    "
+                    import os
+
+                    os.environ.setdefault('DJANGO_SETTINGS_MODULE', 'project.settings')
+                    ",
+                ),
+                ("project/__init__.py", ""),
+                ("project/settings.py", &settings),
+                ("blog/__init__.py", ""),
+                ("blog/templatetags/__init__.py", ""),
+                (
+                    "blog/templatetags/blog_extras.py",
+                    "
+                    from django import template
+
+                    register = template.Library()
+
+                    @register.filter
+                    def shout(value):
+                        return value
+                    ",
+                ),
+                ("blog/templates/blog/post.html", template),
+            ],
+            &[
+                ("django/__init__.py", ""),
+                ("django/contrib/__init__.py", ""),
+                ("django/contrib/humanize/__init__.py", ""),
+                ("django/contrib/humanize/templatetags/__init__.py", ""),
+                (
+                    "django/contrib/humanize/templatetags/humanize.py",
+                    "
+                    from django.template import Library
+
+                    register = Library()
+
+                    @register.filter
+                    def intcomma(value):
+                        '''adds thousand separators.'''
+                        return value
+                    ",
+                ),
+            ],
+        )
+    }
+
     #[test]
     fn a_position_outside_a_construct_offers_nothing() {
         assert!(project("<p>he<CURSOR>llo</p>").completions().is_empty());
@@ -1047,6 +1165,7 @@ mod tests {
         assert_eq!(
             test.detailed(),
             [
+                "api-root",
                 "book-list — books",
                 "book-detail — books",
                 "book-mark-read — books"
@@ -1074,6 +1193,65 @@ mod tests {
         assert!(!completions.contains(&"i18n".to_string()));
     }
 
+    #[test]
+    fn load_offers_an_installed_apps_library() {
+        let completions = with_humanize("{% load <CURSOR> %}", "").detailed();
+
+        assert!(completions.contains(&"humanize — django".to_string()));
+        assert!(completions.contains(&"blog_extras — this project".to_string()));
+    }
+
+    #[test]
+    fn a_filter_from_an_installed_apps_library_is_offered_with_the_load_it_needs() {
+        let test = with_humanize("{% load humanize %}{{ x|<CURSOR> }}", "");
+
+        assert!(
+            test.detailed()
+                .contains(&"intcomma — {% load humanize %}".to_string()),
+            "django's own `humanize` filter is as available as the table's are"
+        );
+
+        let edit = django_template_completions(&test.db, test.file, test.offset)
+            .into_iter()
+            .find(|completion| completion.label == "intcomma")
+            .and_then(|completion| completion.additional_edit);
+        assert!(
+            edit.is_none(),
+            "the template loaded it already, so no second `{{% load %}}` is written"
+        );
+    }
+
+    #[test]
+    fn a_filter_from_an_unloaded_installed_library_brings_its_load_with_it() {
+        let test = with_humanize("{{ x|<CURSOR> }}", "");
+
+        let edit = django_template_completions(&test.db, test.file, test.offset)
+            .into_iter()
+            .find(|completion| completion.label == "intcomma")
+            .and_then(|completion| completion.additional_edit)
+            .expect("`intcomma` to come with the load it needs");
+        assert_eq!(edit.text, "{% load humanize %}\n");
+    }
+
+    #[test]
+    fn a_library_loaded_into_every_template_is_neither_offered_nor_loaded() {
+        let options = "'builtins': ['django.contrib.humanize.templatetags.humanize']";
+
+        assert!(
+            !with_humanize("{% load <CURSOR> %}", options)
+                .completions()
+                .contains(&"humanize".to_string()),
+            "every template has it already, so a `{{% load %}}` for it is noise"
+        );
+
+        let test = with_humanize("{{ x|<CURSOR> }}", options);
+        let intcomma = django_template_completions(&test.db, test.file, test.offset)
+            .into_iter()
+            .find(|completion| completion.label == "intcomma")
+            .expect("the filter to be offered without a `{% load %}`");
+        assert!(intcomma.additional_edit.is_none());
+    }
+
     #[test]
     fn a_bare_name_offers_the_views_context() {
         let completions = project("{{ <CURSOR> }}").completions();
diff --git a/crates/ty_ide/src/django_template/goto.rs b/crates/ty_ide/src/django_template/goto.rs
index caffb91fc0..8044157aed 100644
--- a/crates/ty_ide/src/django_template/goto.rs
+++ b/crates/ty_ide/src/django_template/goto.rs
@@ -165,12 +165,10 @@ impl Site<'_> {
         match self.tag {
             // `{% load static %}` points at the module the library lives in
             "load" => Some(
-                project::registrations(db, db.project())
+                project::tag_libraries(db, db.project())
                     .iter()
-                    .filter(|registration| registration.library == text)
-                    .map(|registration| {
-                        NavigationTarget::new(registration.file, TextRange::default())
-                    })
+                    .filter(|library| library.name == text)
+                    .map(|library| NavigationTarget::new(library.file, TextRange::default()))
                     .collect(),
             ),
             // `{% partial card %}` points at the `{% partialdef card %}`, which
@@ -437,6 +435,65 @@ mod tests {
         assert_eq!(definitions, ["/blog/templatetags/blog_extras.py:"]);
     }
 
+    /// the same, with a mock `django.contrib.humanize` installed beside the project
+    fn with_humanize(template: &str) -> TemplateTest {
+        TemplateTest::with_site_packages(
+            &[
+                (
+                    "manage.py",
+                    "
+                    import os
+
+                    os.environ.setdefault('DJANGO_SETTINGS_MODULE', 'project.settings')
+                    ",
+                ),
+                ("project/__init__.py", ""),
+                (
+                    "project/settings.py",
+                    "INSTALLED_APPS = ['django.contrib.humanize']\n",
+                ),
+                ("blog/templates/blog/post.html", template),
+            ],
+            &[
+                ("django/__init__.py", ""),
+                ("django/contrib/__init__.py", ""),
+                ("django/contrib/humanize/__init__.py", ""),
+                ("django/contrib/humanize/templatetags/__init__.py", ""),
+                (
+                    "django/contrib/humanize/templatetags/humanize.py",
+                    "
+                    from django.template import Library
+
+                    register = Library()
+
+                    @register.filter
+                    def intcomma(value):
+                        return value
+                    ",
+                ),
+            ],
+        )
+    }
+
+    #[test]
+    fn an_installed_apps_filter_navigates_into_the_app_that_registers_it() {
+        let definitions =
+            with_humanize("{% load humanize %}{{ x|intc<CURSOR>omma }}").definitions();
+        assert_eq!(
+            definitions,
+            ["/site-packages/django/contrib/humanize/templatetags/humanize.py:intcomma"]
+        );
+    }
+
+    #[test]
+    fn load_navigates_to_an_installed_apps_library_too() {
+        let definitions = with_humanize("{% load huma<CURSOR>nize %}").definitions();
+        assert_eq!(
+            definitions,
+            ["/site-packages/django/contrib/humanize/templatetags/humanize.py:"]
+        );
+    }
+
     #[test]
     fn a_partial_navigates_to_the_partialdef_that_declares_it() {
         let definitions =
diff --git a/crates/ty_ide/src/django_template/project.rs b/crates/ty_ide/src/django_template/project.rs
index 8655b6282d..60319aea0c 100644
--- a/crates/ty_ide/src/django_template/project.rs
+++ b/crates/ty_ide/src/django_template/project.rs
@@ -23,6 +23,8 @@ use ruff_db::system::{FileType, SystemPath, SystemPathBuf};
 use ruff_python_ast::visitor::{Visitor, walk_expr, walk_stmt};
 use ruff_python_ast::{self as ast, AnyNodeRef, Expr, Stmt};
 use ruff_text_size::{Ranged, TextRange};
+use rustc_hash::{FxHashMap, FxHashSet};
+use ty_module_resolver::{Module, ModuleName, resolve_module, resolve_real_module};
 use ty_project::{Db, Project};
 use ty_python_semantic::SemanticModel;
 use ty_python_semantic::types::ide_support::{
@@ -38,6 +40,43 @@ const STATIC_DIRECTORY: &str = "static";
 /// the package name a project's template tag libraries live in
 const TEMPLATETAGS_PACKAGE: &str = "templatetags";
 
+/// the environment variable a project names its settings module with
+const SETTINGS_MODULE_VARIABLE: &str = "DJANGO_SETTINGS_MODULE";
+
+/// the file stem of the script whose `DJANGO_SETTINGS_MODULE` is the one that counts
+const SETTINGS_ENTRY_POINT: &str = "manage";
+
+/// the setting that configures the template engines
+const TEMPLATES_SETTING: &str = "TEMPLATES";
+
+/// the key an engine lists its own template directories under
+const DIRS_KEY: &str = "DIRS";
+
+/// the key an engine turns the app-directories loader on with
+const APP_DIRS_KEY: &str = "APP_DIRS";
+
+/// the setting that names the project-wide static directories
+const STATICFILES_DIRS_SETTING: &str = "STATICFILES_DIRS";
+
+/// the setting that names the installed apps, in the order they are searched
+const INSTALLED_APPS_SETTING: &str = "INSTALLED_APPS";
+
+/// the key an engine passes its own options under
+const OPTIONS_KEY: &str = "OPTIONS";
+
+/// the option naming the libraries every template has loaded already
+const BUILTINS_OPTION: &str = "builtins";
+
+/// django's own package, whose `templatetags` is a library candidate like any
+/// installed app's
+const DJANGO_PACKAGE: &str = "django";
+
+/// the name a module's own path is bound to
+const FILE_NAME: &str = "__file__";
+
+/// the `pathlib` attribute that walks a path upwards
+const PARENT_ATTRIBUTE: &str = "parent";
+
 /// the functions that render a named template with a context
 pub(crate) const CONTEXT_CALLEES: &[&str] = &["render", "TemplateResponse"];
 
@@ -53,12 +92,30 @@ pub(crate) const REVERSE_CALLEES: &[&str] = &["reverse", "reverse_lazy"];
 /// path just as happily as a route name, and so cannot be read as one on sight.
 pub(crate) const REDIRECT_CALLEE: &str = "redirect";
 
+/// the setting that names the module the project's url tree starts at
+const ROOT_URLCONF_SETTING: &str = "ROOT_URLCONF";
+
 /// the functions that give a route a reversible name
 const URL_CALLEES: &[&str] = &["path", "re_path", "url"];
 
 /// the keyword those functions take the name by
 const URL_NAME_KEYWORD: &str = "name";
 
+/// the function that mounts another url configuration under a prefix
+const INCLUDE_CALLEE: &str = "include";
+
+/// the keyword an include gives its instance namespace by
+const NAMESPACE_KEYWORD: &str = "namespace";
+
+/// the name a module namespaces the routes it holds under
+const APP_NAME_VARIABLE: &str = "app_name";
+
+/// the name a url configuration module holds its routes under
+const URLPATTERNS_VARIABLE: &str = "urlpatterns";
+
+/// the separator django writes between a namespace and the name it qualifies
+const NAMESPACE_SEPARATOR: char = ':';
+
 /// the method a rest framework router routes a viewset with
 const ROUTER_REGISTER_METHOD: &str = "register";
 
@@ -68,6 +125,30 @@ const ROUTER_BASENAME_KEYWORD: &str = "basename";
 /// the routes a router gives every registered viewset
 const ROUTER_ROUTE_SUFFIXES: &[&str] = &["list", "detail"];
 
+/// what a class a router is built from is called, whoever wrote it
+const ROUTER_CLASS_SUFFIX: &str = "Router";
+
+/// the rest framework router that serves an index of everything registered with it
+const DEFAULT_ROUTER_CLASS: &str = "DefaultRouter";
+
+/// the rest framework routers that serve no index
+const PLAIN_ROUTER_CLASSES: &[&str] = &["SimpleRouter", "BaseRouter"];
+
+/// what a router calls that index unless it says otherwise
+const ROUTER_ROOT_ROUTE: &str = "api-root";
+
+/// the attribute a router names its index by
+const ROUTER_ROOT_VIEW_ATTRIBUTE: &str = "root_view_name";
+
+/// how many base classes deep a router's class is followed
+const MAX_ROUTER_DEPTH: usize = 8;
+
+/// how many includes deep the url tree is walked
+///
+/// a real project nests a handful at most, and a urlconf that includes itself
+/// would nest for ever, so the walk stops here whatever it has found.
+const MAX_URLCONF_DEPTH: usize = 8;
+
 /// the decorator that gives one viewset method a route of its own
 const ACTION_DECORATOR: &str = "action";
 
@@ -98,7 +179,7 @@ pub(crate) enum RegistrationKind {
     Filter,
 }
 
-/// a tag or filter one of the project's `templatetags` modules registers
+/// a tag or filter one of the project's tag libraries registers
 #[derive(Debug, Clone, PartialEq, Eq, get_size2::GetSize)]
 pub(crate) struct Registration {
     pub(crate) name: CompactString,
@@ -109,6 +190,33 @@ pub(crate) struct Registration {
     /// the registered function's name, for navigation
     pub(crate) range: TextRange,
     pub(crate) documentation: Option<Box<str>>,
+    /// whether the library it comes from is django's own
+    pub(crate) django: bool,
+}
+
+/// where a tag library comes from
+#[derive(Debug, Clone, Copy, PartialEq, Eq, get_size2::GetSize)]
+pub(crate) enum LibrarySource {
+    /// django's own, whether shipped in `django.templatetags` or in a contrib app
+    Django,
+    /// one of the project's own `templatetags` modules
+    Project,
+    /// an installed third-party app's
+    Installed,
+}
+
+/// a tag library a template can `{% load %}`
+#[derive(Debug, Clone, PartialEq, Eq, get_size2::GetSize)]
+pub(crate) struct Library {
+    /// the name a `{% load %}` names it by, i.e. the module's own file stem
+    pub(crate) name: CompactString,
+    /// the module the tags and filters are registered in
+    pub(crate) file: File,
+    pub(crate) source: LibrarySource,
+    /// whether every template has it loaded already, without saying `{% load %}`
+    ///
+    /// `TEMPLATES[*]["OPTIONS"]["builtins"]` is how a project asks for that.
+    pub(crate) always_loaded: bool,
 }
 
 /// a name the project's url configuration gives a route
@@ -152,18 +260,34 @@ pub(crate) struct DiscoveredFile {
     /// `{% extends %}`, `{% include %}` and `{% static %}` all use
     pub(crate) name: CompactString,
     pub(crate) path: SystemPathBuf,
+    /// how early django would reach the directory this was found under
+    ///
+    /// two apps may both hold a `base.html`, and only one of them is the one
+    /// django loads. every consumer of a discovery takes the first file of a
+    /// name, so this is what puts that one first.
+    precedence: usize,
 }
 
-/// every file under a `templates` directory of the project
+/// every file under a `templates` directory of the project, or one its settings name
 #[salsa::tracked(returns(ref), heap_size=ruff_memory_usage::heap_size)]
 pub(crate) fn template_files(db: &dyn Db, project: Project) -> Box<[DiscoveredFile]> {
-    discover(db, project, TEMPLATE_DIRECTORY)
+    discover(
+        db,
+        project,
+        TEMPLATE_DIRECTORY,
+        template_search_order(db, project),
+    )
 }
 
-/// every file under a `static` directory of the project
+/// every file under a `static` directory of the project, or one its settings name
 #[salsa::tracked(returns(ref), heap_size=ruff_memory_usage::heap_size)]
 pub(crate) fn static_files(db: &dyn Db, project: Project) -> Box<[DiscoveredFile]> {
-    discover(db, project, STATIC_DIRECTORY)
+    discover(
+        db,
+        project,
+        STATIC_DIRECTORY,
+        static_search_order(db, project),
+    )
 }
 
 /// the file a template name resolves to
@@ -176,25 +300,335 @@ pub(crate) fn resolve_template(db: &dyn Db, name: &str) -> Option<File> {
     system_path_to_file(db, &path).ok()
 }
 
-/// every tag and filter the project registers
+/// every tag and filter the project can use
 #[salsa::tracked(returns(ref), heap_size=ruff_memory_usage::heap_size)]
 pub(crate) fn registrations(db: &dyn Db, project: Project) -> Box<[Registration]> {
-    project_scan(db, project, |db, file| {
-        // only a module inside a `templatetags` package is a tag library, so
-        // there is no point parsing anything else
-        is_templatetags_module(db, file)
-            .then(|| registrations_in_file(db, file).iter().cloned())
-            .into_iter()
-            .flatten()
+    tag_libraries(db, project)
+        .iter()
+        .flat_map(|library| {
+            registrations_in_file(db, library.file)
+                .iter()
+                .map(|registration| Registration {
+                    django: library.source == LibrarySource::Django,
+                    ..registration.clone()
+                })
+        })
+        .collect()
+}
+
+/// every tag library the project can `{% load %}`
+///
+/// the project's own `templatetags` modules are one source; the other is the
+/// installed apps, which is where django's own contrib libraries and any
+/// third-party app's come from. a project whose settings can't be read has only
+/// the first, and behaves as though the second had found nothing.
+#[salsa::tracked(returns(ref), heap_size=ruff_memory_usage::heap_size)]
+pub(crate) fn tag_libraries(db: &dyn Db, project: Project) -> Box<[Library]> {
+    let mut found: Vec<Library> = Vec::new();
+
+    // the project's own, wherever in it they sit. these come first so that an app
+    // that is both the project's and installed is reported as the project's
+    for file in &project.files(db) {
+        if !is_stub(db, file) && is_templatetags_module(db, file) {
+            found.extend(library(db, file, LibrarySource::Project, false));
+        }
+    }
+
+    for installed in installed_libraries(db, project) {
+        merge(&mut found, installed.clone());
+    }
+
+    found.into_boxed_slice()
+}
+
+/// add `discovered` to `found`, or fold it into the one already there
+///
+/// one module is one library however many ways it was reached. the way it was
+/// first reached is the one that says where it came from — an app of the
+/// project's own stays the project's however it is installed — but any of them
+/// saying every template has it loaded already settles that for all of them.
+fn merge(found: &mut Vec<Library>, discovered: Library) {
+    if let Some(existing) = found
+        .iter_mut()
+        .find(|existing| existing.file == discovered.file)
+    {
+        existing.always_loaded |= discovered.always_loaded;
+        return;
+    }
+
+    found.push(discovered);
+}
+
+/// the library `file` is, named the way a `{% load %}` names it
+fn library(db: &dyn Db, file: File, source: LibrarySource, always_loaded: bool) -> Option<Library> {
+    let name = file
+        .path(db)
+        .as_system_path()
+        .and_then(SystemPath::file_stem)?;
+
+    Some(Library {
+        name: name.to_compact_string(),
+        file,
+        source,
+        always_loaded,
+    })
+}
+
+/// the tag libraries the project's installed apps bring with them
+///
+/// this is what django's own `get_installed_libraries` walks: the `templatetags`
+/// subpackage of each installed app, and django's own `django.templatetags`
+/// alongside them. site-packages at large is never searched — an app that isn't
+/// installed contributes nothing, exactly as at render time.
+#[salsa::tracked(returns(ref), heap_size=ruff_memory_usage::heap_size)]
+fn installed_libraries(db: &dyn Db, project: Project) -> Box<[Library]> {
+    let Some(importing) = *settings_file(db, project) else {
+        return Box::default();
+    };
+    let settings = django_settings(db, project);
+
+    let mut found: Vec<Library> = Vec::new();
+
+    for app in std::iter::once(DJANGO_PACKAGE)
+        .chain(settings.installed_apps.iter().map(CompactString::as_str))
+    {
+        let Some(package) = app_package(db, importing, app) else {
+            continue;
+        };
+        let Some(tags) = templatetags_package(db, importing, package) else {
+            continue;
+        };
+        let source = if is_djangos(db, package) {
+            LibrarySource::Django
+        } else {
+            LibrarySource::Installed
+        };
+
+        for module in tags.all_submodules(db) {
+            // a stub carries no `@register.filter` to find, so it is the runtime
+            // module beside it that is scanned — and never both
+            let Some(file) = module.file(db).filter(|file| !is_stub(db, *file)) else {
+                continue;
+            };
+            if let Some(discovered) = library(db, file, source, false) {
+                merge(&mut found, discovered);
+            }
+        }
+    }
+
+    // a library the settings load into every template is available whether or not
+    // any app installs it, and needs no `{% load %}` wherever it came from
+    for path in &settings.always_loaded {
+        let Some(name) = ModuleName::new(path) else {
+            continue;
+        };
+        let Some(file) =
+            resolve_real_module(db, importing, &name).and_then(|module| module.file(db))
+        else {
+            continue;
+        };
+        let source = if name.components().next() == Some(DJANGO_PACKAGE) {
+            LibrarySource::Django
+        } else {
+            LibrarySource::Installed
+        };
+
+        if let Some(discovered) = library(db, file, source, true) {
+            merge(&mut found, discovered);
+        }
+    }
+
+    found.into_boxed_slice()
+}
+
+/// the package an `INSTALLED_APPS` entry names
+///
+/// an entry names either the app's package (`"blog"`) or an `AppConfig` inside it
+/// (`"blog.apps.BlogConfig"`), and django takes the app to be the package the
+/// config lives in — which is the innermost package the entry names. it is the
+/// runtime module that is wanted rather than a stub beside it, since what a
+/// library registers is only ever written in the module that runs.
+fn app_package<'db>(db: &'db dyn Db, importing: File, app: &str) -> Option<Module<'db>> {
+    let segments: Vec<&str> = app.split('.').collect();
+
+    (1..=segments.len()).rev().find_map(|length| {
+        let name = ModuleName::from_components(segments[..length].iter().copied())?;
+        let module = resolve_real_module(db, importing, &name)?;
+
+        module.kind(db).is_package().then_some(module)
     })
 }
 
+/// the `templatetags` package of an app, when it has one
+fn templatetags_package<'db>(
+    db: &'db dyn Db,
+    importing: File,
+    package: Module<'db>,
+) -> Option<Module<'db>> {
+    let mut name = package.name(db).clone();
+    name.extend(&ModuleName::new(TEMPLATETAGS_PACKAGE)?);
+
+    resolve_real_module(db, importing, &name)
+}
+
+/// whether a module is one of django's own
+fn is_djangos(db: &dyn Db, module: Module<'_>) -> bool {
+    module.name(db).components().next() == Some(DJANGO_PACKAGE)
+}
+
+/// whether `file` is a stub, which declares types but registers and renders nothing
+fn is_stub(db: &dyn Db, file: File) -> bool {
+    matches!(file.path(db).extension(), Some("pyi" | "byi"))
+}
+
 /// every name the project's url configuration defines
+///
+/// a project that says where its url tree starts has that tree walked from
+/// there, which is the only way to know which namespace an include puts the
+/// names it mounts under — and the only way to reach a third-party urlconf,
+/// which is no file of the project's own.
+///
+/// a project that says nothing is scanned flat instead: every module of it that
+/// names a route contributes, under its own `app_name` where it has one. that
+/// misses an include's namespace and reaches nothing installed, but it is what a
+/// project whose settings can't be read has, and having more names than django
+/// costs a suggestion where having fewer would cost a wrong diagnostic.
 #[salsa::tracked(returns(ref), heap_size=ruff_memory_usage::heap_size)]
 pub(crate) fn url_names(db: &dyn Db, project: Project) -> Box<[UrlName]> {
-    project_scan(db, project, |db, file| {
-        url_names_in_file(db, file).iter().cloned()
-    })
+    let Some(root) = *root_urlconf(db, project) else {
+        return project_scan(db, project, flat_url_names);
+    };
+
+    let mut walk = UrlWalk {
+        db,
+        found: Vec::new(),
+        visited: FxHashSet::default(),
+    };
+    walk.mount(root, URLPATTERNS_VARIABLE, "", MAX_URLCONF_DEPTH);
+
+    let mut found = walk.found;
+    let mut seen = FxHashSet::default();
+    found.retain(|url| seen.insert((url.name.clone(), url.file, url.range)));
+
+    found.into_boxed_slice()
+}
+
+/// the module the project's url tree starts at
+///
+/// it is a dotted module name like any other, so an installed package may be the
+/// one that holds it.
+#[salsa::tracked]
+fn root_urlconf(db: &dyn Db, project: Project) -> Option<File> {
+    let importing = (*settings_file(db, project))?;
+    let root = django_settings(db, project).root_urlconf.as_ref()?;
+
+    resolve_real_module(db, importing, &ModuleName::new(root)?)?.file(db)
+}
+
+/// the names a module defines read on its own, the way the flat scan reads them
+fn flat_url_names(db: &dyn Db, file: File) -> impl Iterator<Item = UrlName> {
+    let conf = urlconf(db, file);
+    let namespace = conf.app_name.clone().unwrap_or_default();
+
+    conf.entries
+        .iter()
+        .filter_map(move |entry| match &entry.kind {
+            UrlEntryKind::Route(route) => Some(namespaced(route, &namespace)),
+            // an include is a tree the flat scan has no way to walk: the module it
+            // names contributes its own names when the scan reaches it
+            UrlEntryKind::Include(_) => None,
+        })
+}
+
+/// walks the url tree, applying the namespace of every include it goes through
+struct UrlWalk<'db> {
+    db: &'db dyn Db,
+    found: Vec<UrlName>,
+    /// the module, list and namespace triples already walked
+    ///
+    /// a urlconf may include itself, directly or around a loop, and two includes
+    /// of one module under two namespaces are two different sets of names — so
+    /// it is the whole triple that decides whether there is anything left to do.
+    visited: FxHashSet<(File, CompactString, CompactString)>,
+}
+
+impl UrlWalk<'_> {
+    /// walk the routes `binding` of `file` holds, namespaced under `prefix`
+    fn mount(&mut self, file: File, binding: &str, prefix: &str, depth: usize) {
+        if depth == 0
+            || !self.visited.insert((
+                file,
+                binding.to_compact_string(),
+                prefix.to_compact_string(),
+            ))
+        {
+            return;
+        }
+
+        let db = self.db;
+        // including a module mounts its `urlpatterns`, and a route the module
+        // writes outside any list at all is taken along rather than lost
+        let whole_module = binding == URLPATTERNS_VARIABLE;
+
+        for entry in &urlconf(db, file).entries {
+            let mounted = match &entry.binding {
+                Some(bound) => bound == binding,
+                None => whole_module,
+            };
+            if !mounted {
+                continue;
+            }
+
+            match &entry.kind {
+                UrlEntryKind::Route(route) => self.found.push(namespaced(route, prefix)),
+                UrlEntryKind::Include(include) => self.follow(file, include, prefix, depth),
+            }
+        }
+    }
+
+    /// walk what an include mounts, under the namespace it mounts it in
+    fn follow(&mut self, file: File, include: &Include, prefix: &str, depth: usize) {
+        match &include.target {
+            IncludeTarget::Local(binding) => {
+                let prefix = extend(prefix, include.namespace.as_deref());
+                self.mount(file, binding, &prefix, depth - 1);
+            }
+            IncludeTarget::Module(module) => {
+                let Some(included) = ModuleName::new(module)
+                    .and_then(|module| resolve_real_module(self.db, file, &module))
+                    .and_then(|module| module.file(self.db))
+                else {
+                    return;
+                };
+                // an include that names no namespace leaves the included module
+                // to name its own
+                let namespace = include
+                    .namespace
+                    .clone()
+                    .or_else(|| urlconf(self.db, included).app_name.clone());
+                let prefix = extend(prefix, namespace.as_deref());
+
+                self.mount(included, URLPATTERNS_VARIABLE, &prefix, depth - 1);
+            }
+        }
+    }
+}
+
+/// `prefix` with `namespace` qualified under it, as django writes it
+fn extend(prefix: &str, namespace: Option<&str>) -> CompactString {
+    match namespace {
+        Some(namespace) if prefix.is_empty() => namespace.to_compact_string(),
+        Some(namespace) => format!("{prefix}{NAMESPACE_SEPARATOR}{namespace}").to_compact_string(),
+        None => prefix.to_compact_string(),
+    }
+}
+
+/// `route` as it is reversed from under `prefix`
+fn namespaced(route: &UrlName, prefix: &str) -> UrlName {
+    UrlName {
+        name: extend(prefix, Some(&route.name)),
+        ..route.clone()
+    }
 }
 
 /// every template context the project's views build
@@ -242,7 +676,7 @@ where
 
     for file in &project.files(db) {
         // a stub declares types, never a url pattern or a rendered template
-        if file.path(db).extension() == Some("pyi") {
+        if is_stub(db, file) {
             continue;
         }
         found.extend(scan(db, file));
@@ -251,16 +685,52 @@ where
     found.into_boxed_slice()
 }
 
-/// find every file under a directory named `directory`, anywhere in the project
+/// find every file django could load, under the convention and under `order`
 ///
-/// the walk is bounded (see [`DISCOVERY_DEPTH`]) and respects the project's
-/// ignore-file settings, so a repository's dependencies are not crawled.
-fn discover(db: &dyn Db, project: Project, directory: &str) -> Box<[DiscoveredFile]> {
+/// the two are a union rather than a choice. a settings module that can't be
+/// found, or a directory in one that can't be worked out, must leave the
+/// convention-based discovery exactly as it was — under-reporting a template is
+/// what makes a "no such template" wrong, and over-reporting one only costs a
+/// suggestion nobody asked for.
+fn discover(
+    db: &dyn Db,
+    project: Project,
+    directory: &str,
+    order: &SearchOrder,
+) -> Box<[DiscoveredFile]> {
     // walking the file system is invisible to salsa, so the callers' queries would
     // hand back their first answer forever. reading the revision the project bumps
     // on every create and delete is what makes a template added mid-session show up
     let _ = project.file_system_revision(db);
 
+    let mut found = discover_by_convention(db, project, directory, order);
+
+    // a directory the settings name is under no obligation to be called
+    // `templates`, nor to sit under the project root, so it gets a walk of its own
+    for (precedence, root) in order.named.iter().enumerate() {
+        collect_under(db, project, root, precedence, &mut found);
+    }
+
+    found.sort_by(|left, right| {
+        left.name
+            .cmp(&right.name)
+            .then(left.precedence.cmp(&right.precedence))
+            .then(left.path.cmp(&right.path))
+    });
+    found.dedup_by(|left, right| left.name == right.name && left.path == right.path);
+    found.into_boxed_slice()
+}
+
+/// find every file under a directory named `directory`, anywhere in the project
+///
+/// the walk is bounded (see [`DISCOVERY_DEPTH`]) and respects the project's
+/// ignore-file settings, so a repository's dependencies are not crawled.
+fn discover_by_convention(
+    db: &dyn Db,
+    project: Project,
+    directory: &str,
+    order: &SearchOrder,
+) -> Vec<DiscoveredFile> {
     let root = project.root(db);
     let found = Mutex::new(Vec::new());
 
@@ -289,11 +759,14 @@ fn discover(db: &dyn Db, project: Project, directory: &str) -> Box<[DiscoveredFi
                         WalkState::Continue
                     }
                     FileType::File => {
-                        if inside && let Some(name) = relative_to_directory(entry.path(), directory)
+                        if inside
+                            && let Some((under, name)) =
+                                relative_to_directory(entry.path(), directory)
                         {
                             found.lock().unwrap().push(DiscoveredFile {
                                 name,
                                 path: entry.path().to_path_buf(),
+                                precedence: order.rank(under),
                             });
                         }
                         WalkState::Continue
@@ -303,23 +776,69 @@ fn discover(db: &dyn Db, project: Project, directory: &str) -> Box<[DiscoveredFi
             })
         });
 
-    let mut found = found
+    found
         .into_inner()
-        .unwrap_or_else(std::sync::PoisonError::into_inner);
-    found.sort_by(|left, right| left.name.cmp(&right.name).then(left.path.cmp(&right.path)));
-    found.dedup_by(|left, right| left.name == right.name && left.path == right.path);
-    found.into_boxed_slice()
+        .unwrap_or_else(std::sync::PoisonError::into_inner)
+}
+
+/// add every file under `root` to `found`, named the way django would name it
+fn collect_under(
+    db: &dyn Db,
+    project: Project,
+    root: &SystemPath,
+    precedence: usize,
+    found: &mut Vec<DiscoveredFile>,
+) {
+    let collected = Mutex::new(Vec::new());
+
+    db.system()
+        .walk_directory(root)
+        .standard_filters(project.settings(db).src().respect_ignore_files)
+        .ignore_hidden(true)
+        .run(|| {
+            Box::new(|entry| {
+                let Ok(entry) = entry else {
+                    return WalkState::Continue;
+                };
+
+                if matches!(entry.file_type(), FileType::File)
+                    && let Some(name) = relative_to_root(entry.path(), root)
+                {
+                    collected.lock().unwrap().push(DiscoveredFile {
+                        name,
+                        path: entry.path().to_path_buf(),
+                        precedence,
+                    });
+                }
+
+                WalkState::Continue
+            })
+        });
+
+    found.extend(
+        collected
+            .into_inner()
+            .unwrap_or_else(std::sync::PoisonError::into_inner),
+    );
 }
 
-/// the part of `path` below its innermost `directory` ancestor
+/// the innermost `directory` ancestor of `path`, and the part of `path` below it
 ///
 /// `/app/templates/blog/post.html` under `templates` is `blog/post.html`, which
 /// is exactly the name a `{% include %}` writes.
-fn relative_to_directory(path: &SystemPath, directory: &str) -> Option<CompactString> {
+fn relative_to_directory<'a>(
+    path: &'a SystemPath,
+    directory: &str,
+) -> Option<(&'a SystemPath, CompactString)> {
     let root = path
         .ancestors()
         .find(|ancestor| ancestor.file_name() == Some(directory))?;
 
+    Some((root, relative_to_root(path, root)?))
+}
+
+/// the part of `path` below `root`, as django's loader would name it
+fn relative_to_root(path: &SystemPath, root: &SystemPath) -> Option<CompactString> {
     Some(
         path.strip_prefix(root)
             .ok()?
@@ -440,6 +959,9 @@ impl RegistrationVisitor {
             file: self.file,
             range: function.range(),
             documentation,
+            // one module is one library however it was reached, so where it came
+            // from is [`registrations`]' to say rather than this scan's
+            django: false,
         })
     }
 }
@@ -503,64 +1025,594 @@ fn mentions(db: &dyn Db, file: File, names: &[&str]) -> bool {
     names.iter().any(|name| source.contains(name))
 }
 
-/// the url names one module defines
-#[salsa::tracked(returns(ref), heap_size=ruff_memory_usage::heap_size)]
-fn url_names_in_file(db: &dyn Db, file: File) -> Box<[UrlName]> {
-    // a named route is a `path()`-like call carrying a `name=` keyword, or a
-    // rest framework router registration. the viewset a registration names is
-    // read through its definition rather than out of this file, so only the
-    // `register` call itself has to be spelled here for the scan to find one
-    let names_a_route = mentions(db, file, URL_CALLEES) && mentions(db, file, &[URL_NAME_KEYWORD]);
-    if !names_a_route && !mentions(db, file, &[ROUTER_REGISTER_METHOD]) {
-        return Box::default();
+/// where django would look for a kind of file, in the order it looks
+///
+/// django tries the directories the settings name outright before it tries the
+/// installed apps' own, and the apps in the order `INSTALLED_APPS` lists them.
+/// that order is what decides which of two same-named templates is loaded.
+#[derive(Debug, Default, Clone, PartialEq, Eq, get_size2::GetSize)]
+struct SearchOrder {
+    /// the directories the settings name outright
+    named: Box<[SystemPathBuf]>,
+    /// the installed apps' own directories, in the order they are searched
+    apps: Box<[SystemPathBuf]>,
+}
+
+impl SearchOrder {
+    /// how early django would reach `root`, later than anything known if never
+    ///
+    /// a directory the settings say nothing about is still discovered — the
+    /// convention finds it — but nothing says which of two such directories
+    /// django prefers, so they keep their existing order among themselves.
+    fn rank(&self, root: &SystemPath) -> usize {
+        if let Some(index) = self.named.iter().position(|named| **named == *root) {
+            return index;
+        }
+
+        // an app's templates sit one directory below the app itself
+        if let Some(parent) = root.parent()
+            && let Some(index) = self.apps.iter().position(|app| **app == *parent)
+        {
+            return self.named.len() + index;
+        }
+
+        usize::MAX
     }
+}
 
-    let parsed = parsed_module(db, file).load(db);
+/// where django would look for the project's templates
+#[salsa::tracked(returns(ref), heap_size=ruff_memory_usage::heap_size)]
+fn template_search_order(db: &dyn Db, project: Project) -> SearchOrder {
+    let settings = django_settings(db, project);
+
+    SearchOrder {
+        named: settings.template_dirs.clone(),
+        // the app-directories loader is the only thing that searches the
+        // installed apps, so with it off there is no order to speak of. the
+        // directories are still discovered either way
+        apps: if settings.app_directories {
+            app_directories(db, project, &settings.installed_apps)
+        } else {
+            Box::default()
+        },
+    }
+}
 
-    // django namespaces an included module's names under its `app_name`
-    let namespace = parsed.suite().iter().find_map(|statement| {
-        let Stmt::Assign(assign) = statement else {
-            return None;
-        };
-        let [Expr::Name(target)] = assign.targets.as_slice() else {
-            return None;
-        };
-        (target.id == "app_name").then(|| string_literal(&assign.value))?
-    });
+/// where django would look for the project's static files
+#[salsa::tracked(returns(ref), heap_size=ruff_memory_usage::heap_size)]
+fn static_search_order(db: &dyn Db, project: Project) -> SearchOrder {
+    let settings = django_settings(db, project);
+
+    SearchOrder {
+        named: settings.static_dirs.clone(),
+        // `staticfiles` searches the installed apps whatever the template
+        // engines are configured to do
+        apps: app_directories(db, project, &settings.installed_apps),
+    }
+}
 
-    let mut visitor = UrlVisitor {
-        db,
-        file,
-        namespace,
-        found: Vec::new(),
+/// the directory each of `apps` lives in, in the order given
+///
+/// an app that can't be resolved contributes no directory rather than a guessed one.
+fn app_directories(db: &dyn Db, project: Project, apps: &[CompactString]) -> Box<[SystemPathBuf]> {
+    let Some(importing) = *settings_file(db, project) else {
+        return Box::default();
     };
-    visitor.visit_body(parsed.suite());
 
-    visitor.found.into_boxed_slice()
+    apps.iter()
+        .filter_map(|app| {
+            app_package(db, importing, app)?
+                .file(db)?
+                .path(db)
+                .as_system_path()?
+                .parent()
+                .map(SystemPath::to_path_buf)
+        })
+        .collect()
 }
 
-struct UrlVisitor<'db> {
-    db: &'db dyn Db,
-    file: File,
-    namespace: Option<CompactString>,
-    found: Vec<UrlName>,
+/// what the project's django settings module says about where its files live
+#[derive(Debug, Default, Clone, PartialEq, Eq, get_size2::GetSize)]
+struct DjangoSettings {
+    /// the directories `TEMPLATES[*]["DIRS"]` names
+    template_dirs: Box<[SystemPathBuf]>,
+    /// whether any template engine has `APP_DIRS` on
+    app_directories: bool,
+    /// the directories `STATICFILES_DIRS` names
+    static_dirs: Box<[SystemPathBuf]>,
+    /// the apps `INSTALLED_APPS` names, in the order it names them
+    installed_apps: Box<[CompactString]>,
+    /// the module `ROOT_URLCONF` names, where the project's url tree starts
+    root_urlconf: Option<CompactString>,
+    /// the modules `TEMPLATES[*]["OPTIONS"]["builtins"]` names, whose tags and
+    /// filters every template has without saying `{% load %}`
+    always_loaded: Box<[CompactString]>,
 }
 
-impl UrlVisitor<'_> {
-    /// record `name`, under the module's `app_name` if it has one
-    fn record(&mut self, name: &str, file: File, range: TextRange, route: Option<&str>) {
-        let name = match &self.namespace {
-            Some(namespace) => format!("{namespace}:{name}").to_compact_string(),
-            None => name.to_compact_string(),
-        };
+/// what the project's settings module says
+///
+/// only the module `DJANGO_SETTINGS_MODULE` names is read. a settings module
+/// ending in `from .local import *` is a common enough shape, but following it
+/// would mean deciding which of two disagreeing values django ends up with, so
+/// it is not followed and the named module's own answer stands.
+#[salsa::tracked(returns(ref), heap_size=ruff_memory_usage::heap_size)]
+fn django_settings(db: &dyn Db, project: Project) -> DjangoSettings {
+    let Some(file) = *settings_file(db, project) else {
+        return DjangoSettings::default();
+    };
+    let Some(path) = file.path(db).as_system_path() else {
+        return DjangoSettings::default();
+    };
 
-        self.found.push(UrlName {
-            name,
-            file,
-            range,
-            route: route.map(Box::from),
-        });
-    }
+    let parsed = parsed_module(db, file).load(db);
+
+    let mut reader = SettingsReader {
+        paths: PathEvaluator {
+            file: path.to_path_buf(),
+            root: project.root(db).to_path_buf(),
+            names: FxHashMap::default(),
+        },
+        settings: DjangoSettings::default(),
+    };
+    reader.read(parsed.suite());
+
+    reader.settings
+}
+
+/// the settings module the project points `DJANGO_SETTINGS_MODULE` at
+///
+/// a project names it in `manage.py`, and usually again in its `wsgi.py` and
+/// `asgi.py`. where they disagree it is `manage.py` that decides, since that is
+/// the one a developer runs.
+#[salsa::tracked]
+fn settings_file(db: &dyn Db, project: Project) -> Option<File> {
+    let mut naming: Vec<(File, CompactString)> = Vec::new();
+
+    for file in &project.files(db) {
+        // a stub sets no environment variable
+        if is_stub(db, file) {
+            continue;
+        }
+        if let Some(module) = settings_module_in_file(db, file) {
+            naming.push((file, module.clone()));
+        }
+    }
+
+    // the project's files come in no order worth relying on, and the fallback has
+    // to land on the same file twice running
+    naming.sort_by(|(left, _), (right, _)| left.path(db).as_str().cmp(right.path(db).as_str()));
+
+    let (importing, module) = naming
+        .iter()
+        .find(|(file, _)| {
+            file.path(db)
+                .as_system_path()
+                .and_then(SystemPath::file_stem)
+                == Some(SETTINGS_ENTRY_POINT)
+        })
+        .or_else(|| naming.first())?;
+
+    resolve_module(db, *importing, &ModuleName::new(module)?)?.file(db)
+}
+
+/// the settings module `file` points `DJANGO_SETTINGS_MODULE` at
+#[salsa::tracked(returns(ref), heap_size=ruff_memory_usage::heap_size)]
+fn settings_module_in_file(db: &dyn Db, file: File) -> Option<CompactString> {
+    if !mentions(db, file, &[SETTINGS_MODULE_VARIABLE]) {
+        return None;
+    }
+
+    let parsed = parsed_module(db, file).load(db);
+    let mut visitor = SettingsModuleVisitor { found: None };
+    visitor.visit_body(parsed.suite());
+
+    visitor.found
+}
+
+/// finds the one string that names the settings module
+struct SettingsModuleVisitor {
+    found: Option<CompactString>,
+}
+
+impl<'ast> Visitor<'ast> for SettingsModuleVisitor {
+    fn visit_stmt(&mut self, stmt: &'ast Stmt) {
+        // `os.environ["DJANGO_SETTINGS_MODULE"] = "project.settings"`
+        if self.found.is_none()
+            && let Stmt::Assign(assign) = stmt
+            && let [Expr::Subscript(subscript)] = assign.targets.as_slice()
+            && string_literal(&subscript.slice).as_deref() == Some(SETTINGS_MODULE_VARIABLE)
+        {
+            self.found = string_literal(&assign.value);
+            return;
+        }
+
+        walk_stmt(self, stmt);
+    }
+
+    fn visit_expr(&mut self, expr: &'ast Expr) {
+        // `os.environ.setdefault("DJANGO_SETTINGS_MODULE", "project.settings")`,
+        // and every other two-string call that sets the variable the same way
+        if self.found.is_none()
+            && let Expr::Call(call) = expr
+            && let [variable, module] = call.arguments.args.as_ref()
+            && string_literal(variable).as_deref() == Some(SETTINGS_MODULE_VARIABLE)
+        {
+            self.found = string_literal(module);
+            return;
+        }
+
+        walk_expr(self, expr);
+    }
+}
+
+/// reads a settings module's assignments into the settings that matter here
+struct SettingsReader {
+    paths: PathEvaluator,
+    settings: DjangoSettings,
+}
+
+impl SettingsReader {
+    /// read every setting the module assigns at its top level
+    ///
+    /// a setting written any other way — built up by a helper, mutated after the
+    /// fact as `TEMPLATES[0]["DIRS"] += …` — is not read, and contributes
+    /// nothing rather than something wrong.
+    fn read(&mut self, body: &[Stmt]) {
+        let mut template_dirs = Vec::new();
+        let mut static_dirs = Vec::new();
+        let mut installed_apps = Vec::new();
+
+        for statement in body {
+            let Stmt::Assign(assign) = statement else {
+                continue;
+            };
+            let [Expr::Name(target)] = assign.targets.as_slice() else {
+                continue;
+            };
+
+            match target.id.as_str() {
+                TEMPLATES_SETTING => self.engines(&assign.value, &mut template_dirs),
+                STATICFILES_DIRS_SETTING => static_dirs.extend(self.directories(&assign.value)),
+                INSTALLED_APPS_SETTING => {
+                    installed_apps
+                        .extend(elements(&assign.value).iter().filter_map(string_literal));
+                }
+                ROOT_URLCONF_SETTING => {
+                    self.settings.root_urlconf = string_literal(&assign.value);
+                }
+                // any other name may be the `BASE_DIR` the directories above are
+                // written against, so it is worked out in case one of them is
+                _ => {
+                    if let Some(path) = self.paths.path(&assign.value) {
+                        self.paths.names.insert(target.id.to_compact_string(), path);
+                    }
+                }
+            }
+        }
+
+        self.settings.template_dirs = template_dirs.into_boxed_slice();
+        self.settings.static_dirs = static_dirs.into_boxed_slice();
+        self.settings.installed_apps = installed_apps.into_boxed_slice();
+    }
+
+    /// read the `DIRS` and `APP_DIRS` of every configured template engine
+    fn engines(&mut self, expr: &Expr, dirs: &mut Vec<SystemPathBuf>) {
+        for engine in elements(expr) {
+            let Expr::Dict(engine) = engine else {
+                continue;
+            };
+
+            for item in &engine.items {
+                let Some(key) = item.key.as_ref().and_then(string_literal) else {
+                    continue;
+                };
+
+                match key.as_str() {
+                    DIRS_KEY => dirs.extend(self.directories(&item.value)),
+                    APP_DIRS_KEY => {
+                        if matches!(&item.value, Expr::BooleanLiteral(literal) if literal.value) {
+                            self.settings.app_directories = true;
+                        }
+                    }
+                    OPTIONS_KEY => self.options(&item.value),
+                    _ => {}
+                }
+            }
+        }
+    }
+
+    /// read the engine options that matter here
+    ///
+    /// `builtins` is the one: a module it names is loaded into every template the
+    /// engine renders, so nothing in a template has to `{% load %}` it.
+    fn options(&mut self, expr: &Expr) {
+        let Expr::Dict(options) = expr else {
+            return;
+        };
+
+        let mut always_loaded: Vec<CompactString> = self.settings.always_loaded.to_vec();
+
+        for item in &options.items {
+            if item.key.as_ref().and_then(string_literal).as_deref() == Some(BUILTINS_OPTION) {
+                always_loaded.extend(elements(&item.value).iter().filter_map(string_literal));
+            }
+        }
+
+        self.settings.always_loaded = always_loaded.into_boxed_slice();
+    }
+
+    /// the directories a list of them names, the ones that can't be worked out dropped
+    fn directories(&self, expr: &Expr) -> Vec<SystemPathBuf> {
+        elements(expr)
+            .iter()
+            .filter_map(|element| self.paths.path(element))
+            .collect()
+    }
+}
+
+/// the elements of a list or tuple literal, and nothing for anything else
+fn elements(expr: &Expr) -> &[Expr] {
+    match expr {
+        Expr::List(list) => &list.elts,
+        Expr::Tuple(tuple) => &tuple.elts,
+        _ => &[],
+    }
+}
+
+/// works out which directory a settings expression names
+///
+/// settings write their directories as often as not through a `BASE_DIR`, itself
+/// a `pathlib` or `os.path` expression over `__file__`. only what reduces to a
+/// directory is answered: an environment lookup, a call into the project's own
+/// code, or a name assigned somewhere other than the module's top level all stay
+/// unresolved, and an unresolved directory is one django is not told about here.
+struct PathEvaluator {
+    /// the settings module's own path, which is what `__file__` is
+    file: SystemPathBuf,
+    /// what a relative directory is taken against
+    root: SystemPathBuf,
+    /// the module-level names already worked out, `BASE_DIR` chief among them
+    names: FxHashMap<CompactString, SystemPathBuf>,
+}
+
+impl PathEvaluator {
+    fn path(&self, expr: &Expr) -> Option<SystemPathBuf> {
+        match expr {
+            Expr::StringLiteral(literal) => Some(self.root.join(literal.value.to_str())),
+            Expr::Name(name) if name.id == FILE_NAME => Some(self.file.clone()),
+            Expr::Name(name) => self.names.get(name.id.as_str()).cloned(),
+            // `BASE_DIR / "templates"`
+            Expr::BinOp(binary) if binary.op == ast::Operator::Div => {
+                let mut path = self.path(&binary.left)?;
+                path.push(string_literal(&binary.right)?.as_str());
+                Some(path)
+            }
+            Expr::Attribute(attribute) if attribute.attr.as_str() == PARENT_ATTRIBUTE => {
+                Some(self.path(&attribute.value)?.parent()?.to_path_buf())
+            }
+            Expr::Call(call) => self.call(call),
+            _ => None,
+        }
+    }
+
+    /// the directory a call names, for the calls that only ever rewrite one
+    fn call(&self, call: &ast::ExprCall) -> Option<SystemPathBuf> {
+        let callee = callee_name(&call.func)?;
+        let first = call.arguments.args.first();
+
+        match callee.as_str() {
+            // wrappers that hand back the path they are given
+            "Path" | "PurePath" | "PosixPath" | "str" | "abspath" | "realpath" | "normpath" => {
+                self.path(first?)
+            }
+            // the same, written as a method of the path itself
+            "resolve" | "absolute" | "expanduser" => match &*call.func {
+                Expr::Attribute(attribute) => self.path(&attribute.value),
+                _ => None,
+            },
+            "dirname" => Some(self.path(first?)?.parent()?.to_path_buf()),
+            // `os.path.join(BASE_DIR, "templates")`
+            "join" => {
+                let mut arguments = call.arguments.args.iter();
+                let mut path = self.path(arguments.next()?)?;
+
+                for argument in arguments {
+                    path.push(string_literal(argument)?.as_str());
+                }
+                Some(path)
+            }
+            _ => None,
+        }
+    }
+}
+
+/// what one url configuration module contributes
+///
+/// the entries are read without a namespace applied: which namespace a name ends
+/// up under is for the include that reaches it to say, and one module reached
+/// two ways is namespaced two ways.
+#[derive(Debug, Default, Clone, PartialEq, Eq, get_size2::GetSize)]
+struct UrlConf {
+    /// the namespace an include of this module falls back to
+    app_name: Option<CompactString>,
+    entries: Box<[UrlEntry]>,
+}
+
+/// one thing a url configuration module does
+#[derive(Debug, Clone, PartialEq, Eq, get_size2::GetSize)]
+struct UrlEntry {
+    /// the module-level name it is bound under, `urlpatterns` most often
+    ///
+    /// this is what tells an `include(router.urls)` which of the module's lists
+    /// it is mounting, and what keeps a list nothing mounts out of the answer.
+    binding: Option<CompactString>,
+    kind: UrlEntryKind,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, get_size2::GetSize)]
+enum UrlEntryKind {
+    /// a route the module names itself
+    Route(UrlName),
+    /// a list of routes mounted under a namespace of its own
+    Include(Include),
+}
+
+/// another list of routes, and the namespace the including site gives it
+#[derive(Debug, Clone, PartialEq, Eq, get_size2::GetSize)]
+struct Include {
+    target: IncludeTarget,
+    /// the `namespace=`, or the instance namespace the two-tuple form names
+    namespace: Option<CompactString>,
+}
+
+/// what an include mounts
+#[derive(Debug, Clone, PartialEq, Eq, get_size2::GetSize)]
+enum IncludeTarget {
+    /// a urlconf named by its dotted module path, the project's or an installed one
+    Module(CompactString),
+    /// a list of routes bound in the same module
+    Local(CompactString),
+}
+
+/// the url configuration one module holds
+#[salsa::tracked(returns(ref), heap_size=ruff_memory_usage::heap_size)]
+fn urlconf(db: &dyn Db, file: File) -> UrlConf {
+    // a named route is a `path()`-like call carrying a `name=` keyword, or a
+    // rest framework router registration. the viewset a registration names is
+    // read through its definition rather than out of this file, so only the
+    // `register` call itself has to be spelled here for the scan to find one —
+    // and a module that only mounts other modules, or only builds a router,
+    // spells the call that does it
+    let names_a_route = mentions(db, file, URL_CALLEES) && mentions(db, file, &[URL_NAME_KEYWORD]);
+    if !names_a_route
+        && !mentions(
+            db,
+            file,
+            &[ROUTER_REGISTER_METHOD, INCLUDE_CALLEE, ROUTER_CLASS_SUFFIX],
+        )
+    {
+        return UrlConf::default();
+    }
+
+    let parsed = parsed_module(db, file).load(db);
+
+    // django namespaces an included module's names under its `app_name` unless
+    // the include says otherwise
+    let app_name = parsed.suite().iter().find_map(|statement| {
+        let (target, value) = assignment(statement)?;
+        (target == APP_NAME_VARIABLE).then(|| string_literal(value))?
+    });
+
+    let mut visitor = UrlVisitor {
+        db,
+        file,
+        binding: None,
+        found: Vec::new(),
+    };
+    visitor.visit_body(parsed.suite());
+
+    UrlConf {
+        app_name,
+        entries: visitor.found.into_boxed_slice(),
+    }
+}
+
+struct UrlVisitor<'db> {
+    db: &'db dyn Db,
+    file: File,
+    /// the module-level name the statement being visited binds
+    binding: Option<CompactString>,
+    found: Vec<UrlEntry>,
+}
+
+impl UrlVisitor<'_> {
+    /// record `name` as a route of the list `binding`
+    fn record(
+        &mut self,
+        binding: Option<CompactString>,
+        name: &str,
+        file: File,
+        range: TextRange,
+        route: Option<&str>,
+    ) {
+        self.found.push(UrlEntry {
+            binding,
+            kind: UrlEntryKind::Route(UrlName {
+                name: name.to_compact_string(),
+                file,
+                range,
+                route: route.map(Box::from),
+            }),
+        });
+    }
+
+    /// record that the list being bound mounts `target` under `namespace`
+    fn mounts(&mut self, target: IncludeTarget, namespace: Option<CompactString>) {
+        self.found.push(UrlEntry {
+            binding: self.binding.clone(),
+            kind: UrlEntryKind::Include(Include { target, namespace }),
+        });
+    }
+
+    /// the url configuration an `include()` mounts
+    ///
+    /// `include("blog.urls")` mounts another module, `include(router.urls)` a
+    /// list of this one's, and either may be written as a `(target, namespace)`
+    /// pair. an explicit `namespace=` outranks the pair's, and both outrank the
+    /// included module's own `app_name`.
+    fn include_call(&mut self, call: &ast::ExprCall) {
+        if callee_name(&call.func).as_deref() != Some(INCLUDE_CALLEE) {
+            return;
+        }
+        let Some(argument) = call.arguments.args.first() else {
+            return;
+        };
+
+        let (target, instance) = match argument {
+            Expr::Tuple(pair) => match pair.elts.as_slice() {
+                [target, instance] => (target, string_literal(instance)),
+                _ => return,
+            },
+            _ => (argument, None),
+        };
+        let Some(target) = include_target(target) else {
+            return;
+        };
+
+        let namespace = call
+            .arguments
+            .find_keyword(NAMESPACE_KEYWORD)
+            .and_then(|keyword| string_literal(&keyword.value))
+            .or(instance);
+
+        self.mounts(target, namespace);
+    }
+
+    /// the index route a router built by `call` serves of its own
+    ///
+    /// a `DefaultRouter` serves one and names it like any other route; a
+    /// `SimpleRouter` serves none. a router class that can't be told apart is
+    /// taken to serve one, since a name offered that django hasn't got costs a
+    /// suggestion where a name missing would cost a wrong diagnostic.
+    fn router_root(&mut self, binding: &str, call: &ast::ExprCall) {
+        if !callee_name(&call.func).is_some_and(|class| class.ends_with(ROUTER_CLASS_SUFFIX)) {
+            return;
+        }
+
+        let name = match router_root_route(self.db, self.file, &call.func, MAX_ROUTER_DEPTH) {
+            RouterRoot::Named(name) => name,
+            RouterRoot::None => return,
+            RouterRoot::Unknown => ROUTER_ROOT_ROUTE.to_compact_string(),
+        };
+
+        self.record(
+            Some(binding.to_compact_string()),
+            &name,
+            self.file,
+            call.func.range(),
+            None,
+        );
+    }
 
     /// the name a `path()`-like call gives its route
     fn path_call(&mut self, call: &ast::ExprCall) {
@@ -575,7 +1627,13 @@ impl UrlVisitor<'_> {
         };
 
         let route = call.arguments.args.first().and_then(string_literal);
-        self.record(&name, self.file, keyword.value.range(), route.as_deref());
+        self.record(
+            self.binding.clone(),
+            &name,
+            self.file,
+            keyword.value.range(),
+            route.as_deref(),
+        );
     }
 
     /// the names a rest framework router's registration makes reversible
@@ -606,6 +1664,13 @@ impl UrlVisitor<'_> {
             return;
         };
 
+        // the routes belong to the router the registration is made on, which is
+        // what an `include(router.urls)` of it will be looking for
+        let binding = match &*method.value {
+            Expr::Name(router) => Some(router.id.to_compact_string()),
+            _ => self.binding.clone(),
+        };
+
         let given = call
             .arguments
             .find_argument_value(ROUTER_BASENAME_KEYWORD, 2)
@@ -633,6 +1698,7 @@ impl UrlVisitor<'_> {
 
         for suffix in ROUTER_ROUTE_SUFFIXES {
             self.record(
+                binding.clone(),
                 &format!("{basename}-{suffix}"),
                 self.file,
                 anchor,
@@ -643,6 +1709,7 @@ impl UrlVisitor<'_> {
         for action in described.iter().flat_map(|described| &described.actions) {
             // an action's route is that method's, so that is where it leads
             self.record(
+                binding.clone(),
                 &format!("{basename}-{}", action.url_name),
                 action.file,
                 action.range,
@@ -652,38 +1719,162 @@ impl UrlVisitor<'_> {
     }
 
     /// what a registered viewset says about the routes it is given
-    ///
-    /// following the name to its class reads another module's ast from this
-    /// module's query, and that cross-file dependency is deliberate: it is what
-    /// makes an `@action` added to a viewset appear in a template's completions
-    /// without the url configuration being touched. it costs one file per
-    /// registration, which is why it is affordable.
     fn viewset(&self, viewset: &Expr) -> Option<ViewSet> {
-        let db = self.db;
-        let model = SemanticModel::new(db, self.file);
-
-        let definitions = match viewset {
-            Expr::Name(name) => definitions_for_name(
-                &model,
-                name.id.as_str(),
-                AnyNodeRef::from(name),
-                ImportAliasResolution::ResolveAliases,
-            ),
-            Expr::Attribute(attribute) => definitions_for_attribute(&model, attribute),
-            _ => return None,
-        };
+        resolved_class(self.db, self.file, viewset, |file, class| ViewSet {
+            basename: default_basename(class),
+            actions: actions(class, file),
+        })
+    }
+}
 
-        definitions.into_iter().find_map(|resolved| {
-            let definition = resolved.definition()?;
-            let file = definition.file(db);
-            let parsed = parsed_module(db, file).load(db);
-            let class = definition.kind(db).as_class()?.node(&parsed);
+/// the class `expr` names, read in the file that defines it
+///
+/// following the name to its class reads another module's ast from this
+/// module's query, and that cross-file dependency is deliberate: it is what
+/// makes an `@action` added to a viewset appear in a template's completions
+/// without the url configuration being touched. it costs one file per name
+/// followed, which is why it is affordable.
+fn resolved_class<T>(
+    db: &dyn Db,
+    file: File,
+    expr: &Expr,
+    read: impl Fn(File, &ast::StmtClassDef) -> T,
+) -> Option<T> {
+    let model = SemanticModel::new(db, file);
+
+    let definitions = match expr {
+        Expr::Name(name) => definitions_for_name(
+            &model,
+            name.id.as_str(),
+            AnyNodeRef::from(name),
+            ImportAliasResolution::ResolveAliases,
+        ),
+        Expr::Attribute(attribute) => definitions_for_attribute(&model, attribute),
+        _ => return None,
+    };
 
-            Some(ViewSet {
-                basename: default_basename(class),
-                actions: actions(class, file),
-            })
-        })
+    definitions.into_iter().find_map(|resolved| {
+        let definition = resolved.definition()?;
+        let defining = definition.file(db);
+        let parsed = parsed_module(db, defining).load(db);
+        let class = definition.kind(db).as_class()?.node(&parsed);
+
+        Some(read(defining, class))
+    })
+}
+
+/// whether a router serves an index of what is registered with it
+#[derive(Debug, Clone)]
+enum RouterRoot {
+    /// it does, under this name
+    Named(CompactString),
+    /// it does not
+    None,
+    /// nothing reachable says either way
+    Unknown,
+}
+
+/// what a router built from the class `expr` names calls its index route
+///
+/// the two rest framework routers are what every other router is written
+/// against, so they are what the class is followed up its bases towards. a class
+/// naming its own `root_view_name` outranks the one it would inherit.
+fn router_root_route(db: &dyn Db, file: File, expr: &Expr, depth: usize) -> RouterRoot {
+    let known = match callee_name(expr) {
+        Some(class) if class == DEFAULT_ROUTER_CLASS => {
+            RouterRoot::Named(ROUTER_ROOT_ROUTE.to_compact_string())
+        }
+        Some(class) if PLAIN_ROUTER_CLASSES.contains(&class.as_str()) => RouterRoot::None,
+        _ => RouterRoot::Unknown,
+    };
+
+    if depth == 0 || !matches!(known, RouterRoot::Unknown) {
+        return known;
+    }
+
+    resolved_class(db, file, expr, |defining, class| {
+        let named = class
+            .body
+            .iter()
+            .find_map(|statement| class_attribute(statement, ROUTER_ROOT_VIEW_ATTRIBUTE))
+            .and_then(|(value, _)| string_literal(value));
+
+        let mut inherited = RouterRoot::Unknown;
+        for base in class.bases() {
+            inherited = router_root_route(db, defining, base, depth - 1);
+            if !matches!(inherited, RouterRoot::Unknown) {
+                break;
+            }
+        }
+
+        match (inherited, named) {
+            (RouterRoot::Named(inherited), named) => RouterRoot::Named(named.unwrap_or(inherited)),
+            (inherited, _) => inherited,
+        }
+    })
+    .unwrap_or(RouterRoot::Unknown)
+}
+
+/// what an include's first argument mounts
+fn include_target(expr: &Expr) -> Option<IncludeTarget> {
+    match expr {
+        Expr::StringLiteral(literal) => Some(IncludeTarget::Module(
+            literal.value.to_str().to_compact_string(),
+        )),
+        _ => Some(IncludeTarget::Local(local_binding(expr)?)),
+    }
+}
+
+/// the module-level name an expression is built from, `router` for `router.urls`
+fn local_binding(expr: &Expr) -> Option<CompactString> {
+    match expr {
+        Expr::Name(name) => Some(name.id.to_compact_string()),
+        Expr::Attribute(attribute) => local_binding(&attribute.value),
+        _ => None,
+    }
+}
+
+/// the module-level lists a bound value is built out of
+///
+/// `urlpatterns = router.urls` and `urlpatterns = [*extra, *router.urls]` both
+/// mount another of the module's lists under no namespace of their own, which is
+/// exactly what an `include()` of that list would do.
+fn mounted_lists(expr: &Expr, found: &mut Vec<CompactString>) {
+    match expr {
+        Expr::Name(_) | Expr::Attribute(_) => found.extend(local_binding(expr)),
+        Expr::List(list) => list
+            .elts
+            .iter()
+            .for_each(|element| mounted_lists(element, found)),
+        Expr::Tuple(tuple) => tuple
+            .elts
+            .iter()
+            .for_each(|element| mounted_lists(element, found)),
+        Expr::Starred(starred) => mounted_lists(&starred.value, found),
+        Expr::BinOp(binary) if binary.op == ast::Operator::Add => {
+            mounted_lists(&binary.left, found);
+            mounted_lists(&binary.right, found);
+        }
+        _ => {}
+    }
+}
+
+/// the module-level name a statement binds, and what it binds to it
+fn assignment(statement: &Stmt) -> Option<(&str, &Expr)> {
+    match statement {
+        Stmt::Assign(assign) => match assign.targets.as_slice() {
+            [Expr::Name(target)] => Some((target.id.as_str(), &*assign.value)),
+            _ => None,
+        },
+        Stmt::AugAssign(assign) => match &*assign.target {
+            Expr::Name(target) => Some((target.id.as_str(), &*assign.value)),
+            _ => None,
+        },
+        Stmt::AnnAssign(assign) => match (&*assign.target, assign.value.as_deref()) {
+            (Expr::Name(target), Some(value)) => Some((target.id.as_str(), value)),
+            _ => None,
+        },
+        _ => None,
     }
 }
 
@@ -775,10 +1966,34 @@ fn actions(class: &ast::StmtClassDef, file: File) -> Vec<Action> {
 }
 
 impl<'ast> Visitor<'ast> for UrlVisitor<'_> {
-    fn visit_expr(&mut self, expr: &'ast Expr) {
-        if let Expr::Call(call) = expr {
-            self.path_call(call);
-            self.router_registration(call);
+    fn visit_stmt(&mut self, stmt: &'ast Stmt) {
+        let Some((binding, value)) = assignment(stmt) else {
+            walk_stmt(self, stmt);
+            return;
+        };
+        let binding = binding.to_compact_string();
+        let outer = self.binding.replace(binding.clone());
+
+        let mut mounted = Vec::new();
+        mounted_lists(value, &mut mounted);
+        for target in mounted {
+            self.mounts(IncludeTarget::Local(target), None);
+        }
+
+        // a router says which index route it serves where it is built
+        if let Expr::Call(call) = value {
+            self.router_root(&binding, call);
+        }
+
+        walk_stmt(self, stmt);
+        self.binding = outer;
+    }
+
+    fn visit_expr(&mut self, expr: &'ast Expr) {
+        if let Expr::Call(call) = expr {
+            self.path_call(call);
+            self.router_registration(call);
+            self.include_call(call);
         }
 
         walk_expr(self, expr);
@@ -1032,7 +2247,10 @@ mod tests {
 
     use crate::django_template::tests::TemplateTest;
 
-    use super::{RegistrationKind, context_for_template, registrations, url_names};
+    use super::{
+        RegistrationKind, context_for_template, registrations, static_files, tag_libraries,
+        template_files, url_names,
+    };
 
     /// a project of python sources, with a throwaway template to anchor the
     /// harness' cursor
@@ -1042,6 +2260,56 @@ mod tests {
         TemplateTest::new(&all)
     }
 
+    /// the `manage.py` a django project points at its settings with
+    const MANAGE: (&str, &str) = (
+        "manage.py",
+        "
+        import os
+
+        def main():
+            os.environ.setdefault('DJANGO_SETTINGS_MODULE', 'project.settings')
+        ",
+    );
+
+    /// the `BASE_DIR` preamble every generated settings module opens with
+    ///
+    /// the settings module sits at `/project/settings.py`, so this is `/`
+    const BASE_DIR: &str = "
+        from pathlib import Path
+
+        BASE_DIR = Path(__file__).resolve().parent.parent
+        ";
+
+    /// a project with a settings module, given as the body that follows `BASE_DIR`
+    fn configured(settings: &str, sources: &[(&str, &str)]) -> TemplateTest {
+        let settings = format!("{BASE_DIR}\n{settings}");
+
+        let mut all = vec![
+            MANAGE,
+            ("project/__init__.py", ""),
+            ("project/settings.py", &*settings),
+        ];
+        all.extend_from_slice(sources);
+
+        project(&all)
+    }
+
+    /// every template found, as `name -> path`, in the order django would load them
+    fn templates(test: &TemplateTest) -> Vec<String> {
+        template_files(&test.db, test.db.project())
+            .iter()
+            .map(|file| format!("{} -> {}", file.name, file.path))
+            .collect()
+    }
+
+    /// every static file found, as `name -> path`
+    fn statics(test: &TemplateTest) -> Vec<String> {
+        static_files(&test.db, test.db.project())
+            .iter()
+            .map(|file| format!("{} -> {}", file.name, file.path))
+            .collect()
+    }
+
     /// the names the project's url configuration defines, in the order found
     fn names(test: &TemplateTest) -> Vec<String> {
         url_names(&test.db, test.db.project())
@@ -1186,7 +2454,7 @@ mod tests {
             ",
         )]);
 
-        assert_eq!(names(&test), ["book-list", "book-detail"]);
+        assert_eq!(names(&test), ["api-root", "book-list", "book-detail"]);
     }
 
     #[test]
@@ -1205,7 +2473,7 @@ mod tests {
 
         assert_eq!(
             names(&test),
-            ["book-list", "book-detail", "book-mark-read"],
+            ["api-root", "book-list", "book-detail", "book-mark-read"],
             "an underscore of the method's name is a dash of the route's"
         );
     }
@@ -1224,7 +2492,10 @@ mod tests {
             ",
         )]);
 
-        assert_eq!(names(&test), ["book-list", "book-detail", "book-read"]);
+        assert_eq!(
+            names(&test),
+            ["api-root", "book-list", "book-detail", "book-read"]
+        );
     }
 
     #[test]
@@ -1251,7 +2522,7 @@ mod tests {
             ),
         ]);
 
-        assert_eq!(names(&test), ["book-list", "book-detail"]);
+        assert_eq!(names(&test), ["api-root", "book-list", "book-detail"]);
     }
 
     #[test]
@@ -1276,7 +2547,10 @@ mod tests {
             ),
         ]);
 
-        assert_eq!(names(&test), ["book-list", "book-detail", "book-mark-read"]);
+        assert_eq!(
+            names(&test),
+            ["api-root", "book-list", "book-detail", "book-mark-read"]
+        );
     }
 
     #[test]
@@ -1300,7 +2574,7 @@ mod tests {
             ),
         ]);
 
-        assert_eq!(names(&test), ["book-list", "book-detail"]);
+        assert_eq!(names(&test), ["api-root", "book-list", "book-detail"]);
     }
 
     #[test]
@@ -1318,7 +2592,7 @@ mod tests {
             ",
         )]);
 
-        assert_eq!(names(&test), ["book-list", "book-detail"]);
+        assert_eq!(names(&test), ["api-root", "book-list", "book-detail"]);
     }
 
     #[test]
@@ -1329,7 +2603,7 @@ mod tests {
             class BookViewSet:
                 def get_queryset(self): ...
 
-            router = DefaultRouter()
+            router = SimpleRouter()
             router.register('books', BookViewSet)
             ",
         )]);
@@ -1354,7 +2628,353 @@ mod tests {
             ",
         )]);
 
-        assert_eq!(names(&test), ["api:book-list", "api:book-detail"]);
+        assert_eq!(
+            names(&test),
+            ["api:api-root", "api:book-list", "api:book-detail"]
+        );
+    }
+
+    #[test]
+    fn a_simple_router_serves_no_index_route() {
+        let test = project(&[(
+            "app/urls.py",
+            "
+            class BookViewSet: ...
+
+            router = SimpleRouter()
+            router.register('books', BookViewSet, basename='book')
+            ",
+        )]);
+
+        assert_eq!(
+            names(&test),
+            ["book-list", "book-detail"],
+            "only a `DefaultRouter` serves an index of what is registered with it"
+        );
+    }
+
+    #[test]
+    fn a_router_is_the_one_it_is_written_against() {
+        let test = project(&[
+            (
+                "app/routers.py",
+                "
+                from rest_framework.routers import DefaultRouter, SimpleRouter
+
+                class LoudRouter(DefaultRouter): ...
+
+                class QuietRouter(SimpleRouter): ...
+                ",
+            ),
+            (
+                "app/urls.py",
+                "
+                from app.routers import LoudRouter, QuietRouter
+
+                class BookViewSet: ...
+
+                loud = LoudRouter()
+                loud.register('books', BookViewSet, basename='book')
+
+                quiet = QuietRouter()
+                quiet.register('shelves', BookViewSet, basename='shelf')
+                ",
+            ),
+        ]);
+
+        assert_eq!(
+            names(&test),
+            [
+                "api-root",
+                "book-list",
+                "book-detail",
+                "shelf-list",
+                "shelf-detail",
+            ],
+            "a subclass serves the index its base serves, and no other"
+        );
+    }
+
+    #[test]
+    fn a_router_that_names_its_index_route_itself_is_taken_at_its_word() {
+        let test = project(&[
+            (
+                "app/routers.py",
+                "
+                from rest_framework.routers import DefaultRouter
+
+                class NamedRouter(DefaultRouter):
+                    root_view_name = 'index'
+                ",
+            ),
+            (
+                "app/urls.py",
+                "
+                from app.routers import NamedRouter
+
+                router = NamedRouter()
+                ",
+            ),
+        ]);
+
+        assert_eq!(names(&test), ["index"]);
+    }
+
+    /// a project whose settings say where its url tree starts
+    fn routed(sources: &[(&str, &str)]) -> TemplateTest {
+        configured("ROOT_URLCONF = 'project.urls'", sources)
+    }
+
+    #[test]
+    fn a_name_reached_through_an_include_takes_the_modules_own_app_name() {
+        let test = routed(&[
+            (
+                "project/urls.py",
+                "urlpatterns = [path('blog/', include('blog.urls'))]\n",
+            ),
+            ("blog/__init__.py", ""),
+            (
+                "blog/urls.py",
+                "
+                app_name = 'blog'
+
+                urlpatterns = [path('', index, name='index')]
+                ",
+            ),
+        ]);
+
+        assert_eq!(names(&test), ["blog:index"]);
+    }
+
+    #[test]
+    fn the_namespace_an_include_names_outranks_the_modules_app_name() {
+        let test = routed(&[
+            (
+                "project/urls.py",
+                "urlpatterns = [path('blog/', include('blog.urls', namespace='news'))]\n",
+            ),
+            ("blog/__init__.py", ""),
+            (
+                "blog/urls.py",
+                "
+                app_name = 'blog'
+
+                urlpatterns = [path('', index, name='index')]
+                ",
+            ),
+        ]);
+
+        assert_eq!(names(&test), ["news:index"]);
+    }
+
+    #[test]
+    fn an_include_may_name_its_namespace_by_a_pair() {
+        let test = routed(&[
+            (
+                "project/urls.py",
+                "
+                urlpatterns = [
+                    path('blog/', include(('blog.urls', 'blog'))),
+                    path('news/', include(('blog.urls', 'blog'), namespace='news')),
+                ]
+                ",
+            ),
+            ("blog/__init__.py", ""),
+            (
+                "blog/urls.py",
+                "urlpatterns = [path('', index, name='index')]\n",
+            ),
+        ]);
+
+        assert_eq!(
+            names(&test),
+            ["blog:index", "news:index"],
+            "the same module included twice is two namespaces of names"
+        );
+    }
+
+    #[test]
+    fn nested_includes_compose_their_namespaces() {
+        let test = routed(&[
+            (
+                "project/urls.py",
+                "urlpatterns = [path('api/', include('api.urls', namespace='api'))]\n",
+            ),
+            ("api/__init__.py", ""),
+            (
+                "api/urls.py",
+                "urlpatterns = [path('v1/', include('api.v1.urls'))]\n",
+            ),
+            ("api/v1/__init__.py", ""),
+            (
+                "api/v1/urls.py",
+                "
+                app_name = 'v1'
+
+                urlpatterns = [path('books/', listing, name='books')]
+                ",
+            ),
+        ]);
+
+        assert_eq!(names(&test), ["api:v1:books"]);
+    }
+
+    #[test]
+    fn an_installed_urlconf_is_walked_like_one_of_the_projects_own() {
+        // the project's own files are the only ones the flat scan can see, so an
+        // include of a package's urlconf is only ever reached through the tree
+        let test = installed(
+            "
+            ROOT_URLCONF = 'project.urls'
+            ",
+            &[(
+                "project/urls.py",
+                "urlpatterns = [path('auth/', include('rest_framework.urls'))]\n",
+            )],
+            &[
+                ("rest_framework/__init__.py", ""),
+                (
+                    "rest_framework/urls.py",
+                    "
+                    app_name = 'rest_framework'
+
+                    urlpatterns = [
+                        path('login/', LoginView, name='login'),
+                        path('logout/', LogoutView, name='logout'),
+                    ]
+                    ",
+                ),
+            ],
+        );
+
+        assert_eq!(
+            names(&test),
+            ["rest_framework:login", "rest_framework:logout"]
+        );
+    }
+
+    #[test]
+    fn a_router_reached_through_an_include_takes_that_includes_namespace() {
+        let test = routed(&[
+            (
+                "project/urls.py",
+                "urlpatterns = [path('api/', include('api.urls', namespace='api'))]\n",
+            ),
+            ("api/__init__.py", ""),
+            (
+                "api/urls.py",
+                "
+                class BookViewSet: ...
+
+                router = DefaultRouter()
+                router.register('books', BookViewSet, basename='book')
+
+                urlpatterns = router.urls
+                ",
+            ),
+        ]);
+
+        assert_eq!(
+            names(&test),
+            ["api:api-root", "api:book-list", "api:book-detail"],
+            "the list a module mounts under its own name is mounted with it"
+        );
+    }
+
+    #[test]
+    fn a_list_of_the_module_may_be_included_under_a_namespace_of_its_own() {
+        let test = routed(&[
+            (
+                "project/urls.py",
+                "urlpatterns = [path('api/', include('api.urls'))]\n",
+            ),
+            ("api/__init__.py", ""),
+            (
+                "api/urls.py",
+                "
+                class BookViewSet: ...
+
+                router = SimpleRouter()
+                router.register('books', BookViewSet, basename='book')
+
+                urlpatterns = [path('v1/', include((router.urls, 'v1')))]
+                ",
+            ),
+        ]);
+
+        assert_eq!(names(&test), ["v1:book-list", "v1:book-detail"]);
+    }
+
+    #[test]
+    fn a_list_nothing_mounts_names_nothing() {
+        let test = routed(&[
+            (
+                "project/urls.py",
+                "urlpatterns = [path('blog/', include('blog.urls'))]\n",
+            ),
+            ("blog/__init__.py", ""),
+            (
+                "blog/urls.py",
+                "
+                urlpatterns = [path('', index, name='index')]
+
+                unused = [path('draft/', draft, name='draft')]
+                ",
+            ),
+        ]);
+
+        assert_eq!(
+            names(&test),
+            ["index"],
+            "django reverses what its tree reaches, and reaches only `urlpatterns`"
+        );
+    }
+
+    #[test]
+    fn a_urlconf_that_includes_itself_still_answers() {
+        let test = routed(&[(
+            "project/urls.py",
+            "
+            urlpatterns = [
+                path('again/', include('project.urls')),
+                path('', index, name='index'),
+            ]
+            ",
+        )]);
+
+        assert_eq!(names(&test), ["index"]);
+    }
+
+    #[test]
+    fn a_project_without_a_root_urlconf_is_scanned_flat() {
+        // the same tree with nothing naming its root: every module that names a
+        // route contributes, under its own `app_name`, and no include is followed
+        let test = configured(
+            "
+            INSTALLED_APPS = ['blog']
+            ",
+            &[
+                (
+                    "project/urls.py",
+                    "urlpatterns = [path('blog/', include('blog.urls', namespace='news'))]\n",
+                ),
+                ("blog/__init__.py", ""),
+                (
+                    "blog/urls.py",
+                    "
+                    app_name = 'blog'
+
+                    urlpatterns = [path('', index, name='index')]
+                    ",
+                ),
+            ],
+        );
+
+        assert_eq!(
+            names(&test),
+            ["blog:index"],
+            "the include's namespace is unknown without the tree that applies it"
+        );
     }
 
     #[test]
@@ -1482,6 +3102,261 @@ mod tests {
         assert_eq!(found, [("shout", RegistrationKind::Filter)]);
     }
 
+    #[test]
+    fn a_directory_the_settings_name_holds_templates_the_convention_never_finds() {
+        let test = configured(
+            "
+            TEMPLATES = [{'DIRS': [BASE_DIR / 'shared'], 'APP_DIRS': True}]
+            ",
+            &[("shared/site/banner.html", "")],
+        );
+
+        assert_eq!(
+            templates(&test),
+            [
+                "app/page.html -> /app/templates/app/page.html",
+                "site/banner.html -> /shared/site/banner.html",
+            ],
+            "the settings' directory adds to what the convention already found"
+        );
+    }
+
+    #[test]
+    fn a_directory_may_be_named_by_a_plain_string() {
+        let test = configured(
+            "
+            TEMPLATES = [{'DIRS': ['shared']}]
+            ",
+            &[("shared/site/banner.html", "")],
+        );
+
+        assert!(templates(&test).contains(&"site/banner.html -> /shared/site/banner.html".into()));
+    }
+
+    #[test]
+    fn a_directory_may_be_joined_the_os_path_way() {
+        let test = configured(
+            "
+            import os
+
+            TEMPLATES = [{'DIRS': [os.path.join(BASE_DIR, 'shared')]}]
+            ",
+            &[("shared/site/banner.html", "")],
+        );
+
+        assert!(templates(&test).contains(&"site/banner.html -> /shared/site/banner.html".into()));
+    }
+
+    #[test]
+    fn a_directory_that_cannot_be_worked_out_is_skipped_and_nothing_else_is() {
+        let test = configured(
+            "
+            import os
+
+            TEMPLATES = [{'DIRS': [os.environ['TEMPLATE_ROOT'], BASE_DIR / 'shared']}]
+            ",
+            &[("shared/site/banner.html", "")],
+        );
+
+        assert_eq!(
+            templates(&test),
+            [
+                "app/page.html -> /app/templates/app/page.html",
+                "site/banner.html -> /shared/site/banner.html",
+            ],
+            "an unresolvable directory costs only itself"
+        );
+    }
+
+    #[test]
+    fn a_project_without_a_settings_module_is_discovered_by_convention_alone() {
+        // the same settings, with nothing pointing at them: `manage.py` is what
+        // makes a settings module the project's, and a directory only it names
+        // must stay unknown
+        let settings = format!("{BASE_DIR}\nTEMPLATES = [{{'DIRS': [BASE_DIR / 'shared']}}]");
+        let test = project(&[
+            ("project/__init__.py", ""),
+            ("project/settings.py", &settings),
+            ("shared/site/banner.html", ""),
+        ]);
+
+        assert_eq!(
+            templates(&test),
+            ["app/page.html -> /app/templates/app/page.html"]
+        );
+    }
+
+    #[test]
+    fn installed_apps_decides_which_of_two_same_named_templates_leads() {
+        let test = configured(
+            "
+            INSTALLED_APPS = ['second', 'first']
+
+            TEMPLATES = [{'APP_DIRS': True}]
+            ",
+            &[
+                ("first/__init__.py", ""),
+                ("first/templates/base.html", ""),
+                ("second/__init__.py", ""),
+                ("second/templates/base.html", ""),
+            ],
+        );
+
+        assert_eq!(
+            templates(&test),
+            [
+                "app/page.html -> /app/templates/app/page.html",
+                "base.html -> /second/templates/base.html",
+                "base.html -> /first/templates/base.html",
+            ],
+            "the app installed first is the one django's loader reaches first"
+        );
+    }
+
+    #[test]
+    fn an_app_may_be_installed_by_the_config_class_inside_it() {
+        let test = configured(
+            "
+            INSTALLED_APPS = ['second.apps.SecondConfig', 'first']
+
+            TEMPLATES = [{'APP_DIRS': True}]
+            ",
+            &[
+                ("first/__init__.py", ""),
+                ("first/templates/base.html", ""),
+                ("second/__init__.py", ""),
+                ("second/apps.py", "class SecondConfig: ...\n"),
+                ("second/templates/base.html", ""),
+            ],
+        );
+
+        assert_eq!(
+            templates(&test)[1],
+            "base.html -> /second/templates/base.html",
+            "the app is the package the config lives in"
+        );
+    }
+
+    #[test]
+    fn without_the_app_directories_loader_no_app_leads_another() {
+        // django would search none of them, so nothing is known about their
+        // order and they keep the one they already had
+        let test = configured(
+            "
+            INSTALLED_APPS = ['second', 'first']
+
+            TEMPLATES = [{'DIRS': []}]
+            ",
+            &[
+                ("first/__init__.py", ""),
+                ("first/templates/base.html", ""),
+                ("second/__init__.py", ""),
+                ("second/templates/base.html", ""),
+            ],
+        );
+
+        assert_eq!(
+            templates(&test)[1],
+            "base.html -> /first/templates/base.html",
+            "the app directories are still discovered, just not ordered"
+        );
+    }
+
+    #[test]
+    fn a_named_directory_leads_the_app_that_holds_the_same_name() {
+        let test = configured(
+            "
+            INSTALLED_APPS = ['first']
+
+            TEMPLATES = [{'DIRS': [BASE_DIR / 'shared'], 'APP_DIRS': True}]
+            ",
+            &[
+                ("first/__init__.py", ""),
+                ("first/templates/base.html", ""),
+                ("shared/base.html", ""),
+            ],
+        );
+
+        assert_eq!(
+            templates(&test)[1],
+            "base.html -> /shared/base.html",
+            "django tries `DIRS` before it tries the installed apps"
+        );
+    }
+
+    #[test]
+    fn manage_py_decides_where_a_wsgi_module_disagrees() {
+        let test = project(&[
+            MANAGE,
+            (
+                "project/wsgi.py",
+                "
+                import os
+
+                os.environ.setdefault('DJANGO_SETTINGS_MODULE', 'project.production')
+                ",
+            ),
+            ("project/__init__.py", ""),
+            (
+                "project/settings.py",
+                "TEMPLATES = [{'DIRS': ['shared']}]\n",
+            ),
+            (
+                "project/production.py",
+                "TEMPLATES = [{'DIRS': ['other']}]\n",
+            ),
+            ("shared/site/banner.html", ""),
+            ("other/site/other.html", ""),
+        ]);
+
+        let found = templates(&test);
+        assert!(found.contains(&"site/banner.html -> /shared/site/banner.html".into()));
+        assert!(
+            !found.iter().any(|file| file.contains("other.html")),
+            "the settings `manage.py` names are the ones read"
+        );
+    }
+
+    #[test]
+    fn a_settings_module_named_by_a_subscript_is_found_too() {
+        let test = project(&[
+            (
+                "manage.py",
+                "
+                import os
+
+                os.environ['DJANGO_SETTINGS_MODULE'] = 'project.settings'
+                ",
+            ),
+            ("project/__init__.py", ""),
+            (
+                "project/settings.py",
+                "TEMPLATES = [{'DIRS': ['shared']}]\n",
+            ),
+            ("shared/site/banner.html", ""),
+        ]);
+
+        assert!(templates(&test).contains(&"site/banner.html -> /shared/site/banner.html".into()));
+    }
+
+    #[test]
+    fn staticfiles_dirs_are_discovered_the_same_way() {
+        let test = configured(
+            "
+            STATICFILES_DIRS = [BASE_DIR / 'assets']
+            ",
+            &[("assets/site.css", ""), ("app/static/app/app.css", "")],
+        );
+
+        assert_eq!(
+            statics(&test),
+            [
+                "app/app.css -> /app/static/app/app.css",
+                "site.css -> /assets/site.css",
+            ]
+        );
+    }
+
     #[test]
     fn a_module_outside_a_templatetags_package_registers_nothing() {
         let test = project(&[(
@@ -1499,4 +3374,369 @@ mod tests {
 
         assert!(registrations(&test.db, test.db.project()).is_empty());
     }
+
+    /// a project with a settings module and packages installed beside it
+    ///
+    /// the packages go to a site-packages directory outside the project root,
+    /// which is what makes them third-party rather than the project's own.
+    fn installed(
+        settings: &str,
+        sources: &[(&str, &str)],
+        packages: &[(&str, &str)],
+    ) -> TemplateTest {
+        let settings = format!("{BASE_DIR}\n{settings}");
+
+        let mut all = vec![
+            MANAGE,
+            ("project/__init__.py", ""),
+            ("project/settings.py", &*settings),
+            ("app/templates/app/page.html", "<CURSOR>"),
+        ];
+        all.extend_from_slice(sources);
+
+        TemplateTest::with_site_packages(&all, packages)
+    }
+
+    /// a mock django, with the `humanize` contrib app and the `i18n` library
+    ///
+    /// `i18n` is written the way django writes it, with the registered name given
+    /// to the decorator rather than taken from the function.
+    const DJANGO: &[(&str, &str)] = &[
+        ("django/__init__.py", ""),
+        ("django/templatetags/__init__.py", ""),
+        (
+            "django/templatetags/i18n.py",
+            "
+            from django.template import Library
+
+            register = Library()
+
+            @register.tag('translate')
+            def do_translate(parser, token): ...
+
+            @register.tag('localize')
+            def localize_tag(parser, token): ...
+            ",
+        ),
+        ("django/contrib/__init__.py", ""),
+        ("django/contrib/humanize/__init__.py", ""),
+        ("django/contrib/humanize/templatetags/__init__.py", ""),
+        (
+            "django/contrib/humanize/templatetags/humanize.py",
+            "
+            from django.template import Library
+
+            register = Library()
+
+            @register.filter
+            def intcomma(value):
+                '''adds thousand separators.'''
+                return value
+
+            @register.filter(is_safe=True)
+            def naturaltime(value):
+                return value
+            ",
+        ),
+        // a stub beside the runtime module, which is what a `django-stubs`
+        // installation puts there and which registers nothing
+        (
+            "django/contrib/humanize/templatetags/humanize.pyi",
+            "def intcomma(value: object) -> str: ...\n",
+        ),
+    ];
+
+    /// every tag library found, as `name (source)`, always-loaded ones marked
+    fn libraries(test: &TemplateTest) -> Vec<String> {
+        tag_libraries(&test.db, test.db.project())
+            .iter()
+            .map(|library| {
+                format!(
+                    "{} ({:?}{})",
+                    library.name,
+                    library.source,
+                    if library.always_loaded {
+                        ", always loaded"
+                    } else {
+                        ""
+                    }
+                )
+            })
+            .collect()
+    }
+
+    /// every registration found, as `library|name`, django's own marked
+    fn registered(test: &TemplateTest) -> Vec<String> {
+        registrations(&test.db, test.db.project())
+            .iter()
+            .map(|registration| {
+                format!(
+                    "{}|{}{}",
+                    registration.library,
+                    registration.name,
+                    if registration.django { " (django)" } else { "" }
+                )
+            })
+            .collect()
+    }
+
+    #[test]
+    fn a_contrib_apps_library_is_discovered_and_is_djangos() {
+        let test = installed(
+            "
+            INSTALLED_APPS = ['django.contrib.humanize']
+            ",
+            &[],
+            DJANGO,
+        );
+
+        assert_eq!(
+            libraries(&test),
+            ["i18n (Django)", "humanize (Django)"],
+            "django's own `django.templatetags` is a candidate however the apps are configured"
+        );
+        assert_eq!(
+            registered(&test),
+            [
+                "i18n|translate (django)",
+                "i18n|localize (django)",
+                "humanize|intcomma (django)",
+                "humanize|naturaltime (django)",
+            ]
+        );
+    }
+
+    #[test]
+    fn a_contrib_apps_library_leads_to_the_module_that_runs_rather_than_the_stub_beside_it() {
+        let test = installed(
+            "
+            INSTALLED_APPS = ['django.contrib.humanize']
+            ",
+            &[],
+            DJANGO,
+        );
+
+        let intcomma = registrations(&test.db, test.db.project())
+            .iter()
+            .find(|registration| registration.name == "intcomma")
+            .expect("the filter to be discovered");
+
+        assert_eq!(
+            intcomma.file.path(&test.db).to_string(),
+            "/site-packages/django/contrib/humanize/templatetags/humanize.py"
+        );
+    }
+
+    #[test]
+    fn a_third_party_apps_library_is_discovered_but_is_not_djangos() {
+        let test = installed(
+            "
+            INSTALLED_APPS = ['crispy_forms']
+            ",
+            &[],
+            &[
+                ("crispy_forms/__init__.py", ""),
+                ("crispy_forms/templatetags/__init__.py", ""),
+                (
+                    "crispy_forms/templatetags/crispy_forms_tags.py",
+                    "
+                    from django import template
+
+                    register = template.Library()
+
+                    @register.filter
+                    def as_crispy_field(field):
+                        return field
+                    ",
+                ),
+            ],
+        );
+
+        assert_eq!(libraries(&test), ["crispy_forms_tags (Installed)"]);
+        assert_eq!(registered(&test), ["crispy_forms_tags|as_crispy_field"]);
+    }
+
+    #[test]
+    fn an_app_installed_by_its_config_class_brings_its_library_all_the_same() {
+        let test = installed(
+            "
+            INSTALLED_APPS = ['crispy_forms.apps.CrispyFormsConfig']
+            ",
+            &[],
+            &[
+                ("crispy_forms/__init__.py", ""),
+                ("crispy_forms/apps.py", "class CrispyFormsConfig: ...\n"),
+                ("crispy_forms/templatetags/__init__.py", ""),
+                (
+                    "crispy_forms/templatetags/crispy_forms_tags.py",
+                    "
+                    from django import template
+
+                    register = template.Library()
+
+                    @register.filter
+                    def as_crispy_field(field):
+                        return field
+                    ",
+                ),
+            ],
+        );
+
+        assert_eq!(libraries(&test), ["crispy_forms_tags (Installed)"]);
+    }
+
+    #[test]
+    fn an_installed_app_without_templatetags_contributes_nothing() {
+        let test = installed(
+            "
+            INSTALLED_APPS = ['plain_app', 'missing_app']
+            ",
+            &[],
+            &[("plain_app/__init__.py", ""), ("plain_app/models.py", "")],
+        );
+
+        assert!(
+            libraries(&test).is_empty(),
+            "neither an app without a `templatetags` package nor one that isn't there at all"
+        );
+    }
+
+    #[test]
+    fn the_projects_own_library_is_reported_as_its_own_even_when_it_is_installed() {
+        let test = installed(
+            "
+            INSTALLED_APPS = ['app']
+            ",
+            &[
+                ("app/__init__.py", ""),
+                ("app/templatetags/__init__.py", ""),
+                (
+                    "app/templatetags/app_extras.py",
+                    "
+                    from django import template
+
+                    register = template.Library()
+
+                    @register.filter
+                    def shout(value):
+                        return value
+                    ",
+                ),
+            ],
+            &[],
+        );
+
+        assert_eq!(
+            libraries(&test),
+            ["app_extras (Project)"],
+            "one module is one library however many ways it was reached"
+        );
+        assert_eq!(registered(&test), ["app_extras|shout"]);
+    }
+
+    #[test]
+    fn a_library_the_settings_load_into_every_template_needs_no_load() {
+        let test = installed(
+            "
+            INSTALLED_APPS = []
+
+            TEMPLATES = [{
+                'OPTIONS': {'builtins': ['everywhere.templatetags.everywhere_tags']},
+            }]
+            ",
+            &[],
+            &[
+                ("everywhere/__init__.py", ""),
+                ("everywhere/templatetags/__init__.py", ""),
+                (
+                    "everywhere/templatetags/everywhere_tags.py",
+                    "
+                    from django import template
+
+                    register = template.Library()
+
+                    @register.simple_tag
+                    def banner():
+                        return ''
+                    ",
+                ),
+            ],
+        );
+
+        assert_eq!(
+            libraries(&test),
+            ["everywhere_tags (Installed, always loaded)"],
+            "the app it lives in need not be installed for its tags to be everywhere"
+        );
+        assert_eq!(registered(&test), ["everywhere_tags|banner"]);
+    }
+
+    #[test]
+    fn an_installed_apps_library_may_be_loaded_into_every_template_as_well() {
+        let test = installed(
+            "
+            INSTALLED_APPS = ['django.contrib.humanize']
+
+            TEMPLATES = [{
+                'OPTIONS': {'builtins': ['django.contrib.humanize.templatetags.humanize']},
+            }]
+            ",
+            &[],
+            DJANGO,
+        );
+
+        assert_eq!(
+            libraries(&test),
+            ["i18n (Django)", "humanize (Django, always loaded)"],
+            "the two ways of reaching one module fold into one library"
+        );
+    }
+
+    #[test]
+    fn a_project_without_settings_discovers_only_its_own_libraries() {
+        // the same packages installed, with nothing pointing at a settings
+        // module: what django would load is unknown, so the convention alone
+        // answers and nothing third-party is reached
+        let test = TemplateTest::with_site_packages(
+            &[
+                ("app/templates/app/page.html", "<CURSOR>"),
+                ("app/templatetags/__init__.py", ""),
+                (
+                    "app/templatetags/app_extras.py",
+                    "
+                    from django import template
+
+                    register = template.Library()
+
+                    @register.filter
+                    def shout(value):
+                        return value
+                    ",
+                ),
+            ],
+            DJANGO,
+        );
+
+        assert_eq!(libraries(&test), ["app_extras (Project)"]);
+        assert_eq!(registered(&test), ["app_extras|shout"]);
+    }
+
+    #[test]
+    fn a_discovered_library_beats_the_table_where_they_disagree() {
+        // the builtin table puts `{% localize %}` in `l10n`, written against one
+        // version of django; this project's own django registers it in `i18n`,
+        // and it is the project's django that is right about the project
+        let test = installed(
+            "
+            INSTALLED_APPS = []
+            ",
+            &[],
+            DJANGO,
+        );
+
+        assert!(
+            super::super::builtins::tag("localize").is_some_and(|tag| tag.library == Some("l10n"))
+        );
+        assert!(registered(&test).contains(&"i18n|localize (django)".to_string()));
+    }
 }
diff --git a/crates/ty_ide/src/django_template/semantic_tokens.rs b/crates/ty_ide/src/django_template/semantic_tokens.rs
index 9d408b935b..97201e444d 100644
--- a/crates/ty_ide/src/django_template/semantic_tokens.rs
+++ b/crates/ty_ide/src/django_template/semantic_tokens.rs
@@ -7,15 +7,18 @@
 //! of one, and which names the template itself binds.
 
 use ruff_text_size::TextRange;
+use ty_project::Db;
 
 use crate::semantic_tokens::{SemanticToken, SemanticTokenModifier, SemanticTokenType};
 
 use super::builtins;
 use super::index::{BindingOrigin, TemplateIndex};
 use super::lexer::TokenKind;
+use super::project::{self, RegistrationKind};
 
 /// the semantic tokens of a template, restricted to `range` when one is given
 pub(crate) fn semantic_tokens(
+    db: &dyn Db,
     index: &TemplateIndex,
     source: &str,
     range: Option<TextRange>,
@@ -55,7 +58,7 @@ pub(crate) fn semantic_tokens(
         })
         .filter_map(|token| {
             let text = &source[token.range];
-            let (mut token_type, mut modifiers) = classify(token.kind, text)?;
+            let (mut token_type, mut modifiers) = classify(db, token.kind, text)?;
 
             // a definition's range is the name alone, which for a quoted one —
             // `{% block "content" %}` — sits *inside* the token rather than
@@ -80,7 +83,11 @@ pub(crate) fn semantic_tokens(
 
 /// the token type and modifiers a lexed token carries, or `None` when it should
 /// be left to the editor's own grammar
-fn classify(kind: TokenKind, text: &str) -> Option<(SemanticTokenType, SemanticTokenModifier)> {
+fn classify(
+    db: &dyn Db,
+    kind: TokenKind,
+    text: &str,
+) -> Option<(SemanticTokenType, SemanticTokenModifier)> {
     let empty = SemanticTokenModifier::empty();
 
     Some(match kind {
@@ -90,11 +97,13 @@ fn classify(kind: TokenKind, text: &str) -> Option<(SemanticTokenType, SemanticT
         TokenKind::Comment => (SemanticTokenType::Comment, empty),
         TokenKind::TagName => (
             SemanticTokenType::Keyword,
-            default_library(is_djangos_tag(text)),
+            default_library(is_djangos_tag(db, text)),
         ),
         TokenKind::FilterName => (
             SemanticTokenType::Function,
-            default_library(builtins::filter(text).is_some()),
+            default_library(
+                builtins::filter(text).is_some() || registered_by_django(db, text, true),
+            ),
         ),
         TokenKind::Variable => (SemanticTokenType::Variable, empty),
         TokenKind::Attribute => (SemanticTokenType::Property, empty),
@@ -111,11 +120,26 @@ fn classify(kind: TokenKind, text: &str) -> Option<(SemanticTokenType, SemanticT
 /// the builtin table lists a closing tag only as the `closed_by` of the tag it
 /// closes, and a branch tag only as one of its `branches`, but `{% endfor %}` and
 /// `{% empty %}` are as much django's as `{% for %}` is.
-fn is_djangos_tag(name: &str) -> bool {
+fn is_djangos_tag(db: &dyn Db, name: &str) -> bool {
     builtins::tag(name).is_some()
         || builtins::TAGS
             .iter()
             .any(|tag| tag.closed_by == Some(name) || tag.branches.contains(&name))
+        || registered_by_django(db, name, false)
+}
+
+/// whether one of django's own installed libraries registers `name`
+///
+/// a `{% load humanize %}`d filter is django's just as `|upper` is, and a
+/// third-party app's is not — which is the whole difference the modifier marks.
+fn registered_by_django(db: &dyn Db, name: &str, filter: bool) -> bool {
+    project::registrations(db, db.project())
+        .iter()
+        .any(|registration| {
+            registration.django
+                && registration.name == name
+                && (registration.kind == RegistrationKind::Filter) == filter
+        })
 }
 
 fn default_library(is_builtin: bool) -> SemanticTokenModifier {
@@ -133,12 +157,23 @@ mod tests {
     use crate::semantic_tokens::SemanticTokenModifier;
 
     use super::super::index::TemplateIndex;
+    use super::super::tests::TemplateTest;
     use super::semantic_tokens;
 
-    /// render the tokens as `type[+modifier…]:text`
+    /// a project holding nothing but the template the cursor sits in
+    fn empty() -> TemplateTest {
+        TemplateTest::new(&[("app/templates/app/page.html", "<CURSOR>")])
+    }
+
+    /// render the tokens as `type[+modifier…]:text`, against an empty project
     fn highlight(source: &str) -> Vec<String> {
+        highlight_in(&empty(), source)
+    }
+
+    /// the same, against a project that may have tag libraries of its own
+    fn highlight_in(test: &TemplateTest, source: &str) -> Vec<String> {
         let index = TemplateIndex::from_source(source);
-        semantic_tokens(&index, source, None)
+        semantic_tokens(&test.db, &index, source, None)
             .into_iter()
             .map(|token| {
                 let names: Vec<_> = SemanticTokenModifier::all_names()
@@ -197,6 +232,78 @@ mod tests {
         );
     }
 
+    #[test]
+    fn an_installed_apps_filter_is_djangos_only_when_the_app_is() {
+        // `intcomma` is django's, in a contrib app the project installs;
+        // `as_crispy_field` is a third-party app's and is not
+        let test = TemplateTest::with_site_packages(
+            &[
+                (
+                    "manage.py",
+                    "
+                    import os
+
+                    os.environ.setdefault('DJANGO_SETTINGS_MODULE', 'project.settings')
+                    ",
+                ),
+                ("project/__init__.py", ""),
+                (
+                    "project/settings.py",
+                    "INSTALLED_APPS = ['django.contrib.humanize', 'crispy_forms']\n",
+                ),
+                ("blog/templates/blog/post.html", "<CURSOR>"),
+            ],
+            &[
+                ("django/__init__.py", ""),
+                ("django/contrib/__init__.py", ""),
+                ("django/contrib/humanize/__init__.py", ""),
+                ("django/contrib/humanize/templatetags/__init__.py", ""),
+                (
+                    "django/contrib/humanize/templatetags/humanize.py",
+                    "
+                    from django.template import Library
+
+                    register = Library()
+
+                    @register.filter
+                    def intcomma(value):
+                        return value
+                    ",
+                ),
+                ("crispy_forms/__init__.py", ""),
+                ("crispy_forms/templatetags/__init__.py", ""),
+                (
+                    "crispy_forms/templatetags/crispy_forms_filters.py",
+                    "
+                    from django import template
+
+                    register = template.Library()
+
+                    @register.filter
+                    def as_crispy_field(field):
+                        return field
+                    ",
+                ),
+            ],
+        );
+
+        assert_eq!(
+            highlight_in(&test, "{{ x|intcomma }}{{ y|as_crispy_field }}"),
+            [
+                "operator:{{",
+                "variable:x",
+                "operator:|",
+                "function+defaultLibrary:intcomma",
+                "operator:}}",
+                "operator:{{",
+                "variable:y",
+                "operator:|",
+                "function:as_crispy_field",
+                "operator:}}",
+            ]
+        );
+    }
+
     #[test]
     fn builtin_tags_and_their_closing_tags_are_both_djangos() {
         assert_eq!(
@@ -351,7 +458,13 @@ mod tests {
         let index = TemplateIndex::from_source(source);
         let end = u32::try_from(source.len()).unwrap();
 
-        let tokens = semantic_tokens(&index, source, Some(TextRange::new(7.into(), end.into())));
+        let test = empty();
+        let tokens = semantic_tokens(
+            &test.db,
+            &index,
+            source,
+            Some(TextRange::new(7.into(), end.into())),
+        );
         assert_eq!(
             tokens
                 .iter()
@@ -366,7 +479,8 @@ mod tests {
         let source = "{% for x in y %}{{ x.z|upper }}{% endfor %}";
         let index = TemplateIndex::from_source(source);
 
-        let tokens = semantic_tokens(&index, source, None);
+        let test = empty();
+        let tokens = semantic_tokens(&test.db, &index, source, None);
         assert!(
             tokens
                 .windows(2)
diff --git a/docs/basedpython/frameworks/django-templates.md b/docs/basedpython/frameworks/django-templates.md
index c67308b08d..40b7565171 100644
--- a/docs/basedpython/frameworks/django-templates.md
+++ b/docs/basedpython/frameworks/django-templates.md
@@ -16,9 +16,9 @@ what is offered depends on where the caret is.
 | `{{ book.‸ }}`      | the attributes of `book`'s type — for a django model its own fields lead, ahead of what `models.Model` brings         |
 | `{% extends '‸' %}` | the project's template paths                                                                                          |
 | `{% include '‸' %}` | the project's template paths                                                                                          |
-| `{% url '‸' %}`     | the project's route names, namespaced by `app_name`                                                                   |
+| `{% url '‸' %}`     | the project's route names, under the namespaces its `include()`s put them in                                          |
 | `{% static '‸' %}`  | the files under the project's `static` directories                                                                    |
-| `{% load ‸ %}`      | the libraries not yet loaded, django's and the project's                                                              |
+| `{% load ‸ %}`      | the libraries not yet loaded: django's, the installed apps', and the project's                                        |
 | `{% block ‸ %}`     | the blocks the parent template defines and this one hasn't overridden yet                                             |
 | `{% partial ‸ %}`   | the fragments `{% partialdef %}` declares                                                                             |
 
@@ -136,9 +136,29 @@ template directories, static directories and tag libraries are found by their co
 - `**/static/**` — static files, named by their path below `static/`
 - `**/templatetags/*.py` — tag libraries, named by their module
 
-## limitations
+## how the settings are read
+
+the module `manage.py` points `DJANGO_SETTINGS_MODULE` at is read as well, and what it says is added to what the convention already found. a settings module that can't be found, or a value in one that can't be worked out, costs only itself.
+
+| setting                               | what it adds                                                            |
+| ------------------------------------- | ----------------------------------------------------------------------- |
+| `TEMPLATES[*]["DIRS"]`                | template directories that need not be called `templates`                |
+| `TEMPLATES[*]["APP_DIRS"]`            | which of two same-named templates django's loader reaches first         |
+| `TEMPLATES[*]["OPTIONS"]["builtins"]` | libraries every template has loaded already                             |
+| `STATICFILES_DIRS`                    | static directories that need not be called `static`                     |
+| `INSTALLED_APPS`                      | the apps searched, in the order they are searched — and their libraries |
+
+### tag libraries from the installed apps
+
+each installed app's `templatetags` package is scanned the way django's own `get_installed_libraries` walks them, so `{% load humanize %}` completes and `|intcomma` is offered once `django.contrib.humanize` is installed. django's own `django.templatetags` is always a candidate alongside them.
 
-**a `TEMPLATES` setting is not read.** template directories are found by name rather than from `settings.py`, so a `DIRS` entry pointing somewhere else is not picked up.
+only the apps `INSTALLED_APPS` names are looked at — site-packages at large is never searched, so an app that isn't installed contributes nothing, exactly as at render time.
+
+a library in `TEMPLATES[*]["OPTIONS"]["builtins"]` is available in every template without a `{% load %}`, so none is suggested for it and none is written.
+
+a project whose settings cannot be read still has its own `templatetags` modules and django's builtin tables, and behaves exactly as it did before.
+
+## limitations
 
 **the context has to be written where it is passed.** the names are read out of the dict literal in the `render()` call or the view class, so a context built somewhere else and passed by name — `return render(request, "…", context)` — contributes nothing.
 
@@ -146,9 +166,9 @@ template directories, static directories and tag libraries are found by their co
 
 **dictionary lookups don't resolve.** django tries a subscript before an attribute, so `{{ mapping.key }}` works at runtime, but a mapping's keys are values rather than types and completions can only offer attributes.
 
-**`{% url %}` namespaces come from `app_name`.** a namespace given at the `include()` instead is not applied.
+**route names are read by walking the url tree from `ROOT_URLCONF`.** that is where the namespaces come from — the `namespace=` an `include()` gives, or the included module's own `app_name` — and it is what reaches an installed package's urlconf, so `include('rest_framework.urls')` contributes `rest_framework:login` like any route of the project's own. a project whose settings don't say where the tree starts falls back to reading each of its modules on its own: an include's namespace is unknown then, and nothing outside the project is reached.
 
-**a route is named by a `path()` or by a rest framework router.** `router.register('books', BookViewSet, basename='book')` names `book-list` and `book-detail`, and each `@action` on the viewset names one more. a registration whose basename cannot be worked out — no `basename=` and no resolvable `queryset` — names nothing rather than guessing.
+**a route is named by a `path()` or by a rest framework router.** `router.register('books', BookViewSet, basename='book')` names `book-list` and `book-detail`, and each `@action` on the viewset names one more. a `DefaultRouter` names `api-root` besides, where a `SimpleRouter` names none. a registration whose basename cannot be worked out — no `basename=` and no resolvable `queryset` — names nothing rather than guessing.
 
 **a name written in python has to be a literal.** the string in a `render()` or a `reverse()` is read as it is written, so a name built from an f-string, or held in a variable, is just a string.
 

From 575751990f9fa6d1baaca1b24e820b889ab6c4da Mon Sep 17 00:00:00 2001
From: KotlinIsland <65446343+kotlinisland@users.noreply.github.com>
Date: Sat, 8 Aug 2026 21:38:32 +1000
Subject: [PATCH 05/16] a template says when it is wrong, and what refers to it

twelve diagnostics, each silent unless the index behind it is authoritative. a
context is recovered from more than a dict literal written in the `render` call.
a name that crosses the language boundary can be renamed, and a template can say
what uses it
---
 crates/ty/docs/rules.md                       |  361 ++++
 crates/ty_ide/src/code_action.rs              |   52 +-
 crates/ty_ide/src/django_template.rs          |  241 ++-
 .../ty_ide/src/django_template/completion.rs  |  133 +-
 .../ty_ide/src/django_template/diagnostics.rs | 1835 +++++++++++++++++
 crates/ty_ide/src/django_template/hover.rs    |    4 +-
 crates/ty_ide/src/django_template/index.rs    |   66 +-
 crates/ty_ide/src/django_template/project.rs  | 1527 ++++++++++++--
 crates/ty_ide/src/django_template/python.rs   |   30 +-
 .../ty_ide/src/django_template/references.rs  |  625 ++++++
 crates/ty_ide/src/django_template/rename.rs   | 1535 ++++++++++++++
 crates/ty_ide/src/django_template/resolve.rs  |   40 +-
 crates/ty_ide/src/django_template/uses.rs     |  964 +++++++++
 crates/ty_ide/src/lib.rs                      |    6 +-
 .../ty_python_semantic/src/django_template.rs |  315 +++
 crates/ty_python_semantic/src/lib.rs          |    2 +
 .../src/types/ide_support.rs                  |   12 +
 crates/ty_server/src/document.rs              |    2 +-
 crates/ty_server/src/server/api.rs            |   15 +-
 .../ty_server/src/server/api/diagnostics.rs   |   22 +-
 .../src/server/api/requests/code_action.rs    |   28 +-
 .../src/server/api/requests/prepare_rename.rs |   40 +-
 .../src/server/api/requests/references.rs     |   13 +-
 .../src/server/api/requests/rename.rs         |  124 +-
 crates/ty_server/src/server/api/traits.rs     |   10 +-
 .../ty_server/tests/e2e/django_templates.rs   |  445 ++++
 crates/ty_wasm/src/lib.rs                     |    2 +
 .../frameworks/django-templates.md            |    6 +
 ty.schema.json                                |  120 ++
 29 files changed, 8346 insertions(+), 229 deletions(-)
 create mode 100644 crates/ty_ide/src/django_template/diagnostics.rs
 create mode 100644 crates/ty_ide/src/django_template/references.rs
 create mode 100644 crates/ty_ide/src/django_template/rename.rs
 create mode 100644 crates/ty_ide/src/django_template/uses.rs
 create mode 100644 crates/ty_python_semantic/src/django_template.rs

diff --git a/crates/ty/docs/rules.md b/crates/ty/docs/rules.md
index 88359fe5b3..e6e1a3a935 100644
--- a/crates/ty/docs/rules.md
+++ b/crates/ty/docs/rules.md
@@ -3420,6 +3420,39 @@ def func() -> int:
     return "a"  # error: [invalid-return-type]
 ```
 
+## `invalid-route-arguments`
+
+<small>
+Default level: <a href="../../rules#rule-levels" title="This lint has a default level of 'error'."><code>error</code></a> ·
+Added in <a href="https://github.com/astral-sh/ty/releases/tag/0.0.69">0.0.69</a> ·
+<a href="https://github.com/astral-sh/ty/issues?q=sort%3Aupdated-desc%20is%3Aissue%20is%3Aopen%20%22invalid-route-arguments%22" target="_blank">Related issues</a> ·
+<a href="https://github.com/astral-sh/ruff/blob/main/crates%2Fty_python_semantic%2Fsrc%2Fdjango_template.rs#L235" target="_blank">View source</a>
+</small>
+
+
+**What it does**
+
+Checks the arguments a `{% url %}` passes against the route's own pattern.
+
+**Why is this bad?**
+
+Django raises `NoReverseMatch` when it renders the template, so the page
+500s. A route's pattern names the arguments it takes and the converter
+each of them goes through, so a missing, extra or misnamed argument — and
+a literal the converter would reject — is a reversal that cannot match.
+
+Only a route whose whole pattern is known is checked, and a name several
+routes share is reported only when none of them accepts the arguments.
+
+**Examples**
+
+```django
+{# path("<int:pk>/", detail, name="detail") #}
+{% url 'detail' %}          {# error: `pk` is missing #}
+{% url 'detail' pk='x' %}   {# error: `pk` goes through `int` #}
+{% url 'detail' pk=1 %}     {# ok #}
+```
+
 ## `invalid-super-argument`
 
 <small>
@@ -6010,6 +6043,40 @@ class F(NamedTuple):
 
 - [Python documentation: super()](https://docs.python.org/3/library/functions.html#super)
 
+## `template-member-needs-arguments`
+
+<small>
+Default level: <a href="../../rules#rule-levels" title="This lint has a default level of 'warn'."><code>warn</code></a> ·
+Added in <a href="https://github.com/astral-sh/ty/releases/tag/0.0.69">0.0.69</a> ·
+<a href="https://github.com/astral-sh/ty/issues?q=sort%3Aupdated-desc%20is%3Aissue%20is%3Aopen%20%22template-member-needs-arguments%22" target="_blank">Related issues</a> ·
+<a href="https://github.com/astral-sh/ruff/blob/main/crates%2Fty_python_semantic%2Fsrc%2Fdjango_template.rs#L289" target="_blank">View source</a>
+</small>
+
+
+**What it does**
+
+Checks for a `{{ }}` lookup landing on a method that cannot be called
+without arguments.
+
+**Why is this bad?**
+
+Django calls whatever a lookup lands on. A method that needs an argument
+cannot be called, so django renders `string_if_invalid` — the empty string
+by default — silently, with no error and no output.
+
+**Examples**
+
+```python
+class Book:
+    def headline(self, length: int) -> str: ...
+    def title(self) -> str: ...
+```
+
+```django
+{{ book.headline }}    {# warning: renders nothing #}
+{{ book.title }}       {# ok #}
+```
+
 ## `too-many-positional-arguments`
 
 <small>
@@ -6320,6 +6387,35 @@ class C(Generic[T]):
 
 - [Typing spec: Scoping rules for type variables](https://typing.python.org/en/latest/spec/generics.html#scoping-rules-for-type-variables)
 
+## `unclosed-template-block`
+
+<small>
+Default level: <a href="../../rules#rule-levels" title="This lint has a default level of 'error'."><code>error</code></a> ·
+Added in <a href="https://github.com/astral-sh/ty/releases/tag/0.0.69">0.0.69</a> ·
+<a href="https://github.com/astral-sh/ty/issues?q=sort%3Aupdated-desc%20is%3Aissue%20is%3Aopen%20%22unclosed-template-block%22" target="_blank">Related issues</a> ·
+<a href="https://github.com/astral-sh/ruff/blob/main/crates%2Fty_python_semantic%2Fsrc%2Fdjango_template.rs#L28" target="_blank">View source</a>
+</small>
+
+
+**What it does**
+
+Checks for a block tag in a django template whose closing tag is missing.
+
+**Why is this bad?**
+
+Django raises `TemplateSyntaxError` when it compiles the template, so the
+page does not render at all.
+
+Only a tag known to open a block is reported: one of django's own, or one
+the project registers with `@register.simple_block_tag`.
+
+**Examples**
+
+```django
+{% if user.is_staff %}    {# error: no `{% endif %}` #}
+  <p>hello</p>
+```
+
 ## `undeclared-raise`
 
 <small>
@@ -6475,6 +6571,181 @@ def test_thing(no_such_fixture) -> None:  # requests an unknown fixture
     ...
 ```
 
+## `unknown-template-block`
+
+<small>
+Default level: <a href="../../rules#rule-levels" title="This lint has a default level of 'warn'."><code>warn</code></a> ·
+Added in <a href="https://github.com/astral-sh/ty/releases/tag/0.0.69">0.0.69</a> ·
+<a href="https://github.com/astral-sh/ty/issues?q=sort%3Aupdated-desc%20is%3Aissue%20is%3Aopen%20%22unknown-template-block%22" target="_blank">Related issues</a> ·
+<a href="https://github.com/astral-sh/ruff/blob/main/crates%2Fty_python_semantic%2Fsrc%2Fdjango_template.rs#L262" target="_blank">View source</a>
+</small>
+
+
+**What it does**
+
+Checks for a `{% block %}` overriding a block no ancestor template
+declares.
+
+**Why is this bad?**
+
+A child template's blocks are rendered by the parent, so a block the
+parent never declares is never rendered — silently, with no error and no
+output.
+
+Only a block written at the top level of a template that `{% extends %}`
+something is reported. A block nested inside another one is rendered as
+part of its enclosing block and needs no declaration above it.
+
+**Examples**
+
+```django
+{# base.html declares `content`, and nothing else #}
+{% extends "base.html" %}
+{% block sidebar %}hello{% endblock %}    {# warning: never rendered #}
+```
+
+## `unknown-template-filter`
+
+<small>
+Default level: <a href="../../rules#rule-levels" title="This lint has a default level of 'error'."><code>error</code></a> ·
+Added in <a href="https://github.com/astral-sh/ty/releases/tag/0.0.69">0.0.69</a> ·
+<a href="https://github.com/astral-sh/ty/issues?q=sort%3Aupdated-desc%20is%3Aissue%20is%3Aopen%20%22unknown-template-filter%22" target="_blank">Related issues</a> ·
+<a href="https://github.com/astral-sh/ruff/blob/main/crates%2Fty_python_semantic%2Fsrc%2Fdjango_template.rs#L119" target="_blank">View source</a>
+</small>
+
+
+**What it does**
+
+Checks for a filter no library the template can reach registers.
+
+**Why is this bad?**
+
+Django raises `TemplateSyntaxError` when it compiles the template, so the
+page does not render at all.
+
+A filter whose library the template has simply not loaded is reported as
+[`unloaded-template-library`](#unloaded-template-library) instead.
+
+**Examples**
+
+```django
+{{ book.title|uppercase }}    {# error: the filter is `upper` #}
+```
+
+## `unknown-template-library`
+
+<small>
+Default level: <a href="../../rules#rule-levels" title="This lint has a default level of 'error'."><code>error</code></a> ·
+Added in <a href="https://github.com/astral-sh/ty/releases/tag/0.0.69">0.0.69</a> ·
+<a href="https://github.com/astral-sh/ty/issues?q=sort%3Aupdated-desc%20is%3Aissue%20is%3Aopen%20%22unknown-template-library%22" target="_blank">Related issues</a> ·
+<a href="https://github.com/astral-sh/ruff/blob/main/crates%2Fty_python_semantic%2Fsrc%2Fdjango_template.rs#L73" target="_blank">View source</a>
+</small>
+
+
+**What it does**
+
+Checks for a `{% load %}` of a tag library the project does not have.
+
+**Why is this bad?**
+
+Django raises `TemplateSyntaxError` when it compiles the template, so the
+page does not render at all.
+
+A library is a `templatetags` module of the project or of one of the apps
+`INSTALLED_APPS` names. Nothing is reported unless the settings module was
+found and every installed app resolved, since a library that cannot be
+reached is not a library that is missing.
+
+**Examples**
+
+```django
+{% load blog_xtras %}    {# error: the library is `blog_extras` #}
+```
+
+## `unknown-template-tag`
+
+<small>
+Default level: <a href="../../rules#rule-levels" title="This lint has a default level of 'error'."><code>error</code></a> ·
+Added in <a href="https://github.com/astral-sh/ty/releases/tag/0.0.69">0.0.69</a> ·
+<a href="https://github.com/astral-sh/ty/issues?q=sort%3Aupdated-desc%20is%3Aissue%20is%3Aopen%20%22unknown-template-tag%22" target="_blank">Related issues</a> ·
+<a href="https://github.com/astral-sh/ruff/blob/main/crates%2Fty_python_semantic%2Fsrc%2Fdjango_template.rs#L97" target="_blank">View source</a>
+</small>
+
+
+**What it does**
+
+Checks for a tag no library the template can reach registers.
+
+**Why is this bad?**
+
+Django raises `TemplateSyntaxError` when it compiles the template, so the
+page does not render at all.
+
+A tag whose library the template has simply not loaded is reported as
+[`unloaded-template-library`](#unloaded-template-library) instead.
+
+**Examples**
+
+```django
+{% iff user.is_staff %}    {# error: no such tag #}
+```
+
+## `unloaded-template-library`
+
+<small>
+Default level: <a href="../../rules#rule-levels" title="This lint has a default level of 'error'."><code>error</code></a> ·
+Added in <a href="https://github.com/astral-sh/ty/releases/tag/0.0.69">0.0.69</a> ·
+<a href="https://github.com/astral-sh/ty/issues?q=sort%3Aupdated-desc%20is%3Aissue%20is%3Aopen%20%22unloaded-template-library%22" target="_blank">Related issues</a> ·
+<a href="https://github.com/astral-sh/ruff/blob/main/crates%2Fty_python_semantic%2Fsrc%2Fdjango_template.rs#L141" target="_blank">View source</a>
+</small>
+
+
+**What it does**
+
+Checks for a tag or filter used without the `{% load %}` it needs.
+
+**Why is this bad?**
+
+Django raises `TemplateSyntaxError` when it compiles the template, so the
+page does not render at all — the tag exists, but not in this template.
+
+A library named by `TEMPLATES[*]["OPTIONS"]["builtins"]` is loaded into
+every template already and is never reported.
+
+**Examples**
+
+```django
+{% static 'css/site.css' %}    {# error: needs `{% load static %}` #}
+```
+
+## `unmatched-template-close`
+
+<small>
+Default level: <a href="../../rules#rule-levels" title="This lint has a default level of 'error'."><code>error</code></a> ·
+Added in <a href="https://github.com/astral-sh/ty/releases/tag/0.0.69">0.0.69</a> ·
+<a href="https://github.com/astral-sh/ty/issues?q=sort%3Aupdated-desc%20is%3Aissue%20is%3Aopen%20%22unmatched-template-close%22" target="_blank">Related issues</a> ·
+<a href="https://github.com/astral-sh/ruff/blob/main/crates%2Fty_python_semantic%2Fsrc%2Fdjango_template.rs#L51" target="_blank">View source</a>
+</small>
+
+
+**What it does**
+
+Checks for a closing tag in a django template that closes nothing.
+
+**Why is this bad?**
+
+Django raises `TemplateSyntaxError` when it compiles the template, so the
+page does not render at all.
+
+**Examples**
+
+```django
+{% for book in books %}
+  <p>{{ book.title }}</p>
+{% endwith %}    {# error: nothing here opened a `{% with %}` #}
+{% endfor %}
+```
+
 ## `unresolved-attribute`
 
 <small>
@@ -6670,6 +6941,96 @@ Using an undefined variable will raise a `NameError` at runtime.
 print(x)  # error
 ```
 
+## `unresolved-route`
+
+<small>
+Default level: <a href="../../rules#rule-levels" title="This lint has a default level of 'error'."><code>error</code></a> ·
+Added in <a href="https://github.com/astral-sh/ty/releases/tag/0.0.69">0.0.69</a> ·
+<a href="https://github.com/astral-sh/ty/issues?q=sort%3Aupdated-desc%20is%3Aissue%20is%3Aopen%20%22unresolved-route%22" target="_blank">Related issues</a> ·
+<a href="https://github.com/astral-sh/ruff/blob/main/crates%2Fty_python_semantic%2Fsrc%2Fdjango_template.rs#L211" target="_blank">View source</a>
+</small>
+
+
+**What it does**
+
+Checks for a `{% url %}` naming a route the url configuration does not
+have.
+
+**Why is this bad?**
+
+Django raises `NoReverseMatch` when it renders the template, so the page
+500s.
+
+The route names are the ones the walk from `ROOT_URLCONF` finds. A project
+that does not say where its url tree starts, or whose tree could not be
+walked in full, reports nothing.
+
+**Examples**
+
+```django
+<a href="{% url 'blog:detail' book.pk %}">    {# error: it is `blog:detail` #}
+```
+
+## `unresolved-static-file`
+
+<small>
+Default level: <a href="../../rules#rule-levels" title="This lint has a default level of 'warn'."><code>warn</code></a> ·
+Added in <a href="https://github.com/astral-sh/ty/releases/tag/0.0.69">0.0.69</a> ·
+<a href="https://github.com/astral-sh/ty/issues?q=sort%3Aupdated-desc%20is%3Aissue%20is%3Aopen%20%22unresolved-static-file%22" target="_blank">Related issues</a> ·
+<a href="https://github.com/astral-sh/ruff/blob/main/crates%2Fty_python_semantic%2Fsrc%2Fdjango_template.rs#L187" target="_blank">View source</a>
+</small>
+
+
+**What it does**
+
+Checks for a `{% static %}` naming a file that is not there.
+
+**Why is this bad?**
+
+Django's default storage builds the url from the name without checking it,
+so the page renders and the asset 404s — a failure nothing reports.
+
+A name whose directory holds no discovered file at all is left alone: that
+is what a bundle built into `static/` at deploy time looks like, and it is
+not something the source tree can answer.
+
+**Examples**
+
+```django
+{% load static %}
+<link href="{% static 'css/sight.css' %}">    {# warning: it is `css/site.css` #}
+```
+
+## `unresolved-template`
+
+<small>
+Default level: <a href="../../rules#rule-levels" title="This lint has a default level of 'error'."><code>error</code></a> ·
+Added in <a href="https://github.com/astral-sh/ty/releases/tag/0.0.69">0.0.69</a> ·
+<a href="https://github.com/astral-sh/ty/issues?q=sort%3Aupdated-desc%20is%3Aissue%20is%3Aopen%20%22unresolved-template%22" target="_blank">Related issues</a> ·
+<a href="https://github.com/astral-sh/ruff/blob/main/crates%2Fty_python_semantic%2Fsrc%2Fdjango_template.rs#L163" target="_blank">View source</a>
+</small>
+
+
+**What it does**
+
+Checks for an `{% extends %}` or `{% include %}` naming a template that
+is not there.
+
+**Why is this bad?**
+
+Django raises `TemplateDoesNotExist` when it renders the template, so the
+page 500s.
+
+Nothing is reported unless the project's template directories are known:
+a project with no readable settings *and* no directory named `templates`
+is one whose template set cannot be established.
+
+**Examples**
+
+```django
+{% extends "blog/bass.html" %}    {# error: the template is `blog/base.html` #}
+```
+
 ## `unspecialized-reified-generic`
 
 <small>
diff --git a/crates/ty_ide/src/code_action.rs b/crates/ty_ide/src/code_action.rs
index 908994a012..743f2195b3 100644
--- a/crates/ty_ide/src/code_action.rs
+++ b/crates/ty_ide/src/code_action.rs
@@ -1,5 +1,7 @@
 use crate::completion;
+use crate::django_template::django_template_code_actions;
 
+use ruff_db::system::SystemPathBuf;
 use ruff_db::{files::File, parsed::parsed_module};
 use ruff_diagnostics::Edit;
 use ruff_python_ast::find_node::covering_node;
@@ -15,19 +17,43 @@ pub struct QuickFix {
     pub title: String,
     pub edits: Vec<Edit>,
     pub preferred: bool,
+    /// A file the action creates, for a fix to a reference to something that
+    /// isn't there yet.
+    pub create: Option<SystemPathBuf>,
 }
 
+impl QuickFix {
+    fn new(title: String, edits: Vec<Edit>, preferred: bool) -> Self {
+        Self {
+            title,
+            edits,
+            preferred,
+            create: None,
+        }
+    }
+}
+
+/// The quick fixes offered for a diagnostic of `file`.
+///
+/// `template` says the file is a django template rather than python, which the
+/// caller knows and this cannot: nothing about a template may be answered by
+/// parsing it as python.
 pub fn code_actions(
     db: &dyn Db,
     file: File,
     diagnostic_range: TextRange,
     diagnostic_id: &str,
+    template: bool,
 ) -> Vec<QuickFix> {
     let registry = db.lint_registry();
     let Ok(lint_id) = registry.get(diagnostic_id) else {
         return Vec::new();
     };
 
+    if template {
+        return django_template_code_actions(db, file, diagnostic_range, lint_id);
+    }
+
     let mut actions = Vec::new();
 
     // Suggest imports/qualifications for unresolved references (often ideal)
@@ -40,11 +66,11 @@ pub fn code_actions(
     }
 
     // Suggest just suppressing the lint (always a valid option, but never ideal)
-    actions.push(QuickFix {
-        title: format!("Ignore '{}' for this line", lint_id.name()),
-        edits: suppress_single(db, file, lint_id, diagnostic_range).into_edits(),
-        preferred: false,
-    });
+    actions.push(QuickFix::new(
+        format!("Ignore '{}' for this line", lint_id.name()),
+        suppress_single(db, file, lint_id, diagnostic_range).into_edits(),
+        false,
+    ));
 
     actions
 }
@@ -61,11 +87,7 @@ fn unresolved_fixes(
     Some(
         completion::unresolved_fixes(db, file, &parsed, symbol, node)
             .into_iter()
-            .map(|import| QuickFix {
-                title: import.label,
-                edits: vec![import.edit],
-                preferred: true,
-            }),
+            .map(|import| QuickFix::new(import.label, vec![import.edit], true)),
     )
 }
 
@@ -969,7 +991,15 @@ mod tests {
                 .context(0)
                 .format(DiagnosticFormat::Full);
 
-            for mut action in code_actions(&self.db, self.file, self.diagnostic_range, &lint.name) {
+            // every fixture this harness writes is python; the template actions
+            // have their own tests
+            for mut action in code_actions(
+                &self.db,
+                self.file,
+                self.diagnostic_range,
+                &lint.name,
+                false,
+            ) {
                 let mut diagnostic = Diagnostic::new(
                     DiagnosticId::Lint(LintName::of("code-action")),
                     ruff_db::diagnostic::Severity::Info,
diff --git a/crates/ty_ide/src/django_template.rs b/crates/ty_ide/src/django_template.rs
index 1d161c3fb7..f455a7f259 100644
--- a/crates/ty_ide/src/django_template.rs
+++ b/crates/ty_ide/src/django_template.rs
@@ -15,6 +15,7 @@
 
 mod builtins;
 mod completion;
+mod diagnostics;
 mod folding;
 mod goto;
 mod hover;
@@ -22,25 +23,33 @@ mod index;
 mod lexer;
 mod project;
 mod python;
+mod references;
+mod rename;
 mod resolve;
 mod semantic_tokens;
 mod symbols;
+mod uses;
 
 pub use completion::{TemplateCompletion, TemplateEdit};
 pub use hover::{DisplayTemplateHover, TemplateHover};
 pub(crate) use python::{
     string_completions as django_string_completions, string_definition as django_string_definition,
 };
+pub use rename::{PreparedTemplateRename, TemplateRename, TemplateRenameOutcome};
 pub use symbols::TemplateSymbol;
 
+use ruff_db::diagnostic::Diagnostic;
 use ruff_db::files::File;
 use ruff_db::source::source_text;
 use ruff_db::system::SystemPath;
 use ruff_text_size::{TextRange, TextSize};
 use ty_project::Db;
 
+use ty_python_semantic::lint::LintId;
+
+use crate::code_action::QuickFix;
 use crate::semantic_tokens::SemanticTokens;
-use crate::{FoldingRange, NavigationTargets, RangedValue};
+use crate::{FoldingRange, NavigationTargets, RangedValue, ReferenceTarget};
 
 use index::TemplateIndex;
 
@@ -169,6 +178,75 @@ fn ancestors<'db>(
     collected
 }
 
+/// everything wrong with `file`, read as a django template
+///
+/// the type checker never sees a template — it is not python — so this is the
+/// whole of what a template document can report.
+pub fn django_template_diagnostics(db: &dyn Db, file: File) -> Vec<Diagnostic> {
+    let source = source_text(db, file);
+    diagnostics::diagnostics(db, file, template_index(db, file), source.as_str())
+}
+
+/// the quick fixes offered for a template diagnostic at `range`
+pub(crate) fn django_template_code_actions(
+    db: &dyn Db,
+    file: File,
+    range: TextRange,
+    lint: LintId,
+) -> Vec<QuickFix> {
+    let source = source_text(db, file);
+    diagnostics::code_actions(
+        db,
+        file,
+        template_index(db, file),
+        source.as_str(),
+        range,
+        lint,
+    )
+}
+
+/// whether the django name at `offset` of `file` can be renamed
+///
+/// `template` says the file is a django template rather than python, which the
+/// caller knows and this cannot. either language may write one of these names,
+/// and `None` — a position that names nothing django knows — is what leaves a
+/// python file's position to the python services.
+pub fn django_prepare_rename(
+    db: &dyn Db,
+    file: File,
+    offset: TextSize,
+    template: bool,
+) -> Option<PreparedTemplateRename> {
+    rename::prepare(db, file, offset, template)
+}
+
+/// every edit renaming the django name at `offset` of `file` to `new_name` makes
+pub fn django_rename(
+    db: &dyn Db,
+    file: File,
+    offset: TextSize,
+    new_name: &str,
+    template: bool,
+) -> Option<TemplateRenameOutcome> {
+    rename::rename(db, file, offset, new_name, template)
+}
+
+/// every place the django name at `offset` of `file` is written
+///
+/// `template` says the file is a django template rather than python, as for the
+/// rename above. `include_declaration` is the client's, as LSP specifies: with it
+/// off, the block the base declares, the file a template name loads and the
+/// `path(…, name=…)` a route is declared by are all left out of the answer.
+pub fn django_references(
+    db: &dyn Db,
+    file: File,
+    offset: TextSize,
+    include_declaration: bool,
+    template: bool,
+) -> Option<Vec<ReferenceTarget>> {
+    references::references(db, file, offset, include_declaration, template)
+}
+
 /// the completions for `offset` in `file`, read as a django template
 pub fn django_template_completions(
     db: &dyn Db,
@@ -186,7 +264,7 @@ pub(crate) mod tests {
     use ruff_db::system::{DbWithTestSystem, DbWithWritableSystem, SystemPath, SystemPathBuf};
     use ruff_python_ast::PythonVersion;
     use ruff_python_trivia::textwrap::dedent;
-    use ruff_text_size::TextSize;
+    use ruff_text_size::{Ranged, TextSize};
     use ty_module_resolver::SearchPathSettings;
     use ty_project::{ProjectMetadata, TestDb};
     use ty_python_core::platform::PythonPlatform;
@@ -196,13 +274,18 @@ pub(crate) mod tests {
     use crate::MarkupKind;
 
     use super::{
-        TemplateSymbol, django_template_completions, django_template_document_symbols,
-        django_template_folding_ranges, django_template_goto_definition, django_template_hover,
-        is_django_template_path,
+        PreparedTemplateRename, TemplateRenameOutcome, TemplateSymbol, django_prepare_rename,
+        django_references, django_rename, django_template_completions, django_template_diagnostics,
+        django_template_document_symbols, django_template_folding_ranges,
+        django_template_goto_definition, django_template_hover, is_django_template_path,
     };
 
     /// a project whose files are written out, with the cursor marked by
-    /// `<CURSOR>` in exactly one of them
+    /// `<CURSOR>` in at most one of them
+    ///
+    /// a test that has no cursor to place — a diagnostic's, which reads a whole
+    /// file rather than a position in one — leaves the marker out, and the file
+    /// under test is then the last one written.
     pub(crate) struct TemplateTest {
         pub(crate) db: TestDb,
         pub(crate) file: File,
@@ -271,6 +354,7 @@ pub(crate) mod tests {
             const MARKER: &str = "<CURSOR>";
 
             let mut cursor = None;
+            let mut last = None;
 
             for (path, contents) in sources {
                 let contents = dedent(contents).into_owned();
@@ -287,6 +371,7 @@ pub(crate) mod tests {
                 let path = root.join(path);
                 db.write_file(&path, &contents).unwrap();
                 let file = system_path_to_file(&db, &path).unwrap();
+                last = Some(file);
 
                 if let Some(offset) = offset {
                     assert!(cursor.is_none(), "more than one `<CURSOR>` marker");
@@ -294,10 +379,35 @@ pub(crate) mod tests {
                 }
             }
 
-            let (file, offset) = cursor.expect("a source to contain `<CURSOR>`");
+            let (file, offset) = cursor
+                .unwrap_or_else(|| (last.expect("a source to be written"), TextSize::default()));
             Self { db, file, offset }
         }
 
+        /// every diagnostic of the file under test, rendered as
+        /// `rule severity: message [text]`
+        pub(crate) fn diagnostics(&self) -> Vec<String> {
+            let source = ruff_db::source::source_text(&self.db, self.file);
+
+            django_template_diagnostics(&self.db, self.file)
+                .into_iter()
+                .map(|diagnostic| {
+                    let range = diagnostic
+                        .primary_span()
+                        .and_then(|span| span.range())
+                        .unwrap_or_default();
+
+                    format!(
+                        "{} {:?}: {} [{}]",
+                        diagnostic.id(),
+                        diagnostic.severity(),
+                        diagnostic.primary_message(),
+                        &source[range]
+                    )
+                })
+                .collect()
+        }
+
         /// the labels of the completions at the cursor, in the order offered
         pub(crate) fn completions(&self) -> Vec<String> {
             django_template_completions(&self.db, self.file, self.offset)
@@ -369,6 +479,123 @@ pub(crate) mod tests {
             lines
         }
 
+        /// whether the file under test is read as a template rather than python
+        ///
+        /// this is the same question the server answers from what the editor told
+        /// it, and falls back to the same path check when it wasn't told.
+        fn is_template(&self) -> bool {
+            match self.file.path(&self.db) {
+                ruff_db::files::FilePath::System(path) => is_django_template_path(path),
+                _ => false,
+            }
+        }
+
+        /// what the editor is offered for a rename at the cursor
+        pub(crate) fn prepare_rename(&self) -> String {
+            match django_prepare_rename(&self.db, self.file, self.offset, self.is_template()) {
+                None => "no rename".to_string(),
+                Some(PreparedTemplateRename::Refused(why)) => format!("refused: {why}"),
+                Some(PreparedTemplateRename::Ready { range, placeholder }) => {
+                    let source = ruff_db::source::source_text(&self.db, self.file);
+                    format!("rename `{placeholder}`, replacing `{}`", &source[range])
+                }
+            }
+        }
+
+        /// every edit a rename at the cursor would make, as `path:line old -> new`
+        pub(crate) fn rename(&self, new_name: &str) -> Vec<String> {
+            let renamed = django_rename(
+                &self.db,
+                self.file,
+                self.offset,
+                new_name,
+                self.is_template(),
+            );
+
+            let rename = match renamed {
+                None => return vec!["no rename".to_string()],
+                Some(TemplateRenameOutcome::Refused(why)) => {
+                    return vec![format!("refused: {why}")];
+                }
+                Some(TemplateRenameOutcome::Edits(rename)) => rename,
+            };
+
+            let mut lines: Vec<String> = rename
+                .edits
+                .iter()
+                .map(|edit| {
+                    let source = ruff_db::source::source_text(&self.db, edit.file());
+                    let line = source.as_str()[..usize::from(edit.range().start())]
+                        .matches('\n')
+                        .count()
+                        + 1;
+
+                    format!(
+                        "{}:{line} {} -> {new_name}",
+                        // the memory file system reports the host's separator
+                        edit.file().path(&self.db).to_string().replace('\\', "/"),
+                        &source[edit.range()]
+                    )
+                })
+                .collect();
+
+            if let Some((from, to)) = rename.file_rename {
+                lines.push(format!(
+                    "move {} -> {}",
+                    from.as_str().replace('\\', "/"),
+                    to.as_str().replace('\\', "/")
+                ));
+            }
+
+            lines
+        }
+
+        /// every reference at the cursor, as `path:line text`
+        ///
+        /// a declaration is marked, since which occurrences are declarations is
+        /// what `includeDeclaration` turns on and off.
+        pub(crate) fn references(&self) -> Vec<String> {
+            self.references_with_declaration(true)
+        }
+
+        /// the same, as a client that asked for the uses alone gets them
+        pub(crate) fn references_without_declaration(&self) -> Vec<String> {
+            self.references_with_declaration(false)
+        }
+
+        fn references_with_declaration(&self, include_declaration: bool) -> Vec<String> {
+            let found = django_references(
+                &self.db,
+                self.file,
+                self.offset,
+                include_declaration,
+                self.is_template(),
+            );
+
+            found
+                .unwrap_or_default()
+                .into_iter()
+                .map(|target| {
+                    let source = ruff_db::source::source_text(&self.db, target.file());
+                    let line = source.as_str()[..usize::from(target.range().start())]
+                        .matches('\n')
+                        .count()
+                        + 1;
+
+                    format!(
+                        "{}{}:{line} {}",
+                        match target.kind() {
+                            crate::ReferenceKind::Other => "declaration ",
+                            _ => "",
+                        },
+                        // the memory file system reports the host's separator
+                        target.file().path(&self.db).to_string().replace('\\', "/"),
+                        &source[target.range()],
+                    )
+                })
+                .collect()
+        }
+
         /// each foldable range, as the tags that open and close it
         pub(crate) fn folds(&self) -> Vec<String> {
             let source = ruff_db::source::source_text(&self.db, self.file);
diff --git a/crates/ty_ide/src/django_template/completion.rs b/crates/ty_ide/src/django_template/completion.rs
index d6b71ad9d6..c014ec5962 100644
--- a/crates/ty_ide/src/django_template/completion.rs
+++ b/crates/ty_ide/src/django_template/completion.rs
@@ -572,7 +572,7 @@ fn variables(
             .value
             .and_then(|value| resolve::expression_type(db, variable.file, value))
             .map(|ty| ty.display(db).to_string())
-            .or_else(|| Some("from the view's context".to_string()));
+            .or_else(|| Some(variable.source.description().to_string()));
         completions.push(completion);
     }
 
@@ -734,7 +734,7 @@ fn inherited(
 /// the ones it has loaded already, and the ones the settings load into every
 /// template — a `{% load %}` for one of those is not wrong, but it is noise, so
 /// neither is one suggested.
-fn loaded_libraries(db: &dyn Db, index: &TemplateIndex) -> FxHashSet<CompactString> {
+pub(super) fn loaded_libraries(db: &dyn Db, index: &TemplateIndex) -> FxHashSet<CompactString> {
     index
         .loads()
         .iter()
@@ -749,7 +749,7 @@ fn loaded_libraries(db: &dyn Db, index: &TemplateIndex) -> FxHashSet<CompactStri
 }
 
 /// the `{% load %}` a suggestion from `library` needs, when it isn't loaded yet
-fn load_edit_for(
+pub(super) fn load_edit_for(
     index: &TemplateIndex,
     loaded: &FxHashSet<CompactString>,
     library: Option<&str>,
@@ -929,6 +929,84 @@ mod tests {
         )
     }
 
+    /// a project whose settings name two of django's own context processors
+    ///
+    /// what a processor returns is in scope in every template the project
+    /// renders, which is what makes `{{ user }}` complete in a template no view
+    /// ever mentions it to. `context` is the dict the one view passes.
+    fn with_processors(template: &str, context: &str) -> TemplateTest {
+        let view = format!(
+            "
+            from blog.models import Book
+
+            def post(request):
+                return render(request, 'blog/post.html', {context})
+            "
+        );
+
+        TemplateTest::with_site_packages(
+            &[
+                (
+                    "manage.py",
+                    "
+                    import os
+
+                    os.environ.setdefault('DJANGO_SETTINGS_MODULE', 'project.settings')
+                    ",
+                ),
+                ("project/__init__.py", ""),
+                (
+                    "project/settings.py",
+                    "
+                    INSTALLED_APPS = ['blog']
+
+                    TEMPLATES = [{'APP_DIRS': True, 'OPTIONS': {'context_processors': [
+                        'django.template.context_processors.request',
+                        'django.contrib.auth.context_processors.auth',
+                    ]}}]
+                    ",
+                ),
+                ("blog/__init__.py", ""),
+                (
+                    "blog/models.py",
+                    "
+                    class Book:
+                        title: str
+                    ",
+                ),
+                ("blog/views.py", &view),
+                ("blog/templates/blog/post.html", template),
+            ],
+            &[
+                ("django/__init__.py", ""),
+                ("django/template/__init__.py", ""),
+                (
+                    "django/template/context_processors.py",
+                    "
+                    def request(request):
+                        return {'request': request, 'site': 'a blog'}
+                    ",
+                ),
+                ("django/contrib/__init__.py", ""),
+                ("django/contrib/auth/__init__.py", ""),
+                (
+                    "django/contrib/auth/context_processors.py",
+                    "
+                    class User:
+                        username: str
+
+                    class PermWrapper:
+                        def __init__(self, user): ...
+
+                    def auth(request):
+                        user = User()
+                        return {'user': user, 'perms': PermWrapper(user)}
+                    ",
+                ),
+            ],
+        )
+    }
+
     #[test]
     fn a_position_outside_a_construct_offers_nothing() {
         assert!(project("<p>he<CURSOR>llo</p>").completions().is_empty());
@@ -1265,6 +1343,55 @@ mod tests {
         assert_eq!(completions, ["book", "forloop", "shelf", "novel"]);
     }
 
+    #[test]
+    fn a_bare_name_offers_the_context_processors_names_after_the_views() {
+        let completions = with_processors("{{ <CURSOR> }}", "{'book': Book()}").completions();
+        assert_eq!(completions, ["book", "request", "site", "user", "perms"]);
+    }
+
+    #[test]
+    fn a_processors_name_that_has_no_type_still_says_where_it_comes_from() {
+        let completions = with_processors("{{ <CURSOR> }}", "{'book': Book()}").detailed();
+        assert!(
+            completions.contains(&"site — from a context processor".to_string()),
+            "got {completions:?}"
+        );
+    }
+
+    #[test]
+    fn a_context_processors_name_carries_its_type() {
+        let completions = with_processors("{{ user.<CURSOR> }}", "{'book': Book()}").detailed();
+        assert_eq!(completions, ["username — str"]);
+    }
+
+    #[test]
+    fn a_name_the_view_supplies_shadows_the_context_processors() {
+        let test = with_processors("{{ user.<CURSOR> }}", "{'book': Book(), 'user': Book()}");
+        assert_eq!(
+            test.detailed(),
+            ["title — str"],
+            "the view's `user` is what django renders with"
+        );
+
+        let offered = with_processors("{{ <CURSOR> }}", "{'book': Book(), 'user': Book()}")
+            .completions()
+            .iter()
+            .filter(|label| *label == "user")
+            .count();
+        assert_eq!(offered, 1, "and it is offered once");
+    }
+
+    #[test]
+    fn a_name_a_tag_binds_shadows_the_context_processors() {
+        let completions = with_processors(
+            "{% with user=book %}{{ user.<CURSOR> }}{% endwith %}",
+            "{'book': Book()}",
+        )
+        .detailed();
+
+        assert_eq!(completions, ["title — str"]);
+    }
+
     #[test]
     fn a_context_variable_shows_the_type_the_view_gives_it() {
         let completions = project("{{ <CURSOR> }}").detailed();
diff --git a/crates/ty_ide/src/django_template/diagnostics.rs b/crates/ty_ide/src/django_template/diagnostics.rs
new file mode 100644
index 0000000000..297e225f28
--- /dev/null
+++ b/crates/ty_ide/src/django_template/diagnostics.rs
@@ -0,0 +1,1835 @@
+//! what a django template gets wrong
+//!
+//! a template is compiled and rendered rather than type-checked, so the errors
+//! worth reporting are the ones those two steps raise: a tag django cannot parse,
+//! a name django cannot reverse, a file django cannot load. every check here is
+//! one of those, and each says which of the project indexes it reads.
+//!
+//! the one rule the whole module is written around is that **a diagnostic must
+//! never fire on correct code**. an index that cannot answer authoritatively —
+//! because the settings module wasn't found, or because something it named
+//! couldn't be worked out — silences every check that reads it, rather than
+//! reporting against a partial answer. [`project::settings_are_authoritative`]
+//! and [`project::routes_are_authoritative`] are where that is decided.
+
+use compact_str::{CompactString, ToCompactString};
+use ruff_db::diagnostic::{Annotation, Diagnostic, DiagnosticId, Span};
+use ruff_db::files::File;
+use ruff_db::system::SystemPathBuf;
+use ruff_diagnostics::{Edit, Fix};
+use ruff_source_file::OneIndexed;
+use ruff_text_size::{TextRange, TextSize};
+use rustc_hash::FxHashSet;
+use ty_project::Db;
+use ty_python_semantic::django_template::{
+    INVALID_ROUTE_ARGUMENTS, TEMPLATE_MEMBER_NEEDS_ARGUMENTS, UNCLOSED_TEMPLATE_BLOCK,
+    UNKNOWN_TEMPLATE_BLOCK, UNKNOWN_TEMPLATE_FILTER, UNKNOWN_TEMPLATE_LIBRARY,
+    UNKNOWN_TEMPLATE_TAG, UNLOADED_TEMPLATE_LIBRARY, UNMATCHED_TEMPLATE_CLOSE, UNRESOLVED_ROUTE,
+    UNRESOLVED_STATIC_FILE, UNRESOLVED_TEMPLATE,
+};
+use ty_python_semantic::lint::{LintId, LintMetadata};
+use ty_python_semantic::types::ide_support::callable_needs_arguments;
+
+use crate::code_action::QuickFix;
+
+use super::TEMPLATE_DIRECTORY;
+use super::completion::{load_edit_for, loaded_libraries};
+use super::index::{END_TAG_PREFIX, TemplateIndex};
+use super::lexer::{Construct, ConstructKind, Token, TokenKind, string_contents};
+use super::project::{self, RegistrationKind, UrlName};
+use super::resolve;
+use super::{ancestors, builtins};
+
+/// the tag that names a static file
+const STATIC_TAG: &str = "static";
+
+/// the tag that reverses a route
+const URL_TAG: &str = "url";
+
+/// what everything a template says is checked against
+///
+/// the indexes are read once here rather than once per check, since every one of
+/// them is a project-wide query.
+pub(crate) struct Checker<'a> {
+    db: &'a dyn Db,
+    file: File,
+    index: &'a TemplateIndex,
+    source: &'a str,
+    /// the libraries this template has, its own `{% load %}`s and the ones the
+    /// settings load into every template
+    loaded: FxHashSet<CompactString>,
+    /// whether the library index answers for the whole project
+    ///
+    /// a template that loads a library nothing here knows is a template whose
+    /// tags and filters cannot be enumerated, whatever the project-wide index
+    /// says, so this is per template rather than per project.
+    libraries_known: bool,
+    suppressions: Suppressions,
+    found: Vec<Diagnostic>,
+}
+
+/// everything wrong with `file`, read as a django template
+pub(crate) fn diagnostics(
+    db: &dyn Db,
+    file: File,
+    index: &TemplateIndex,
+    source: &str,
+) -> Vec<Diagnostic> {
+    let project = db.project();
+    let loaded = loaded_libraries(db, index);
+
+    let libraries_known = project::settings_are_authoritative(db, project)
+        && index.loads().iter().all(|load| {
+            project::tag_libraries(db, project)
+                .iter()
+                .any(|library| library.name == load.library)
+        });
+
+    let mut checker = Checker {
+        db,
+        file,
+        index,
+        source,
+        loaded,
+        libraries_known,
+        suppressions: Suppressions::of(index, source),
+        found: Vec::new(),
+    };
+
+    checker.unclosed_blocks();
+    checker.unmatched_closes();
+    checker.unknown_libraries();
+    checker.unknown_names();
+    checker.unresolved_templates();
+    checker.unresolved_static_files();
+    checker.routes();
+    checker.unknown_blocks();
+    checker.members_needing_arguments();
+
+    checker.found.sort_by_key(|diagnostic| {
+        diagnostic
+            .primary_span()
+            .and_then(|span| span.range())
+            .map(TextRange::start)
+            .unwrap_or_default()
+    });
+    checker.found
+}
+
+impl Checker<'_> {
+    /// report `lint` over `range`, unless it is turned off or suppressed
+    ///
+    /// the returned diagnostic is the one just recorded, so that a caller with a
+    /// fix or a hint to add can go on building it.
+    fn report(
+        &mut self,
+        lint: &'static LintMetadata,
+        range: TextRange,
+        message: impl std::fmt::Display,
+    ) -> Option<&mut Diagnostic> {
+        let severity = self
+            .db
+            .rule_selection(self.file)
+            .severity(LintId::of(lint))?;
+
+        if self
+            .suppressions
+            .covers(lint, line_of(self.source, range.start()))
+        {
+            return None;
+        }
+
+        let mut diagnostic = Diagnostic::new(DiagnosticId::Lint(lint.name()), severity, message);
+        diagnostic.annotate(Annotation::primary(Span::from(self.file).with_range(range)));
+
+        self.found.push(diagnostic);
+        self.found.last_mut()
+    }
+
+    fn text(&self, range: TextRange) -> &str {
+        &self.source[range]
+    }
+
+    // ---- 1. a block tag that is never closed -------------------------------
+
+    /// django raises `TemplateSyntaxError: Unclosed tag` for one of these
+    ///
+    /// only a tag *known* to open a block is reported. a tag the index took to
+    /// open one because the file happens to hold a matching `{% end… %}`
+    /// elsewhere is a guess, and a guess is not something to report.
+    fn unclosed_blocks(&mut self) {
+        let unclosed: Vec<_> = self
+            .index
+            .spans()
+            .iter()
+            .filter(|block| !block.closed && opens_a_block(self.db, &block.name))
+            .map(|block| (block.name.clone(), block.end_tag.clone(), block.open_range))
+            .collect();
+
+        for (name, end_tag, range) in unclosed {
+            if let Some(diagnostic) = self.report(
+                &UNCLOSED_TEMPLATE_BLOCK,
+                range,
+                format_args!("unclosed `{name}`"),
+            ) {
+                diagnostic.help(format_args!("close it with `{{% {end_tag} %}}`"));
+            }
+        }
+    }
+
+    // ---- 2. a closing tag that closes nothing ------------------------------
+
+    /// django raises `TemplateSyntaxError: Invalid block tag` for one of these
+    ///
+    /// as above, only a name django itself would have been waiting for counts: a
+    /// `{% endmodal %}` belonging to a project's own block tag is left alone,
+    /// since nothing here knows whether `{% modal %}` opens a block at all.
+    fn unmatched_closes(&mut self) {
+        let strays: Vec<_> = self
+            .index
+            .strays()
+            .iter()
+            .filter(|stray| closes_a_block(self.db, &stray.name))
+            .map(|stray| (stray.name.clone(), stray.range))
+            .collect();
+
+        for (name, range) in strays {
+            let opening = name
+                .strip_prefix(END_TAG_PREFIX)
+                .unwrap_or(&name)
+                .to_compact_string();
+            if let Some(diagnostic) = self.report(
+                &UNMATCHED_TEMPLATE_CLOSE,
+                range,
+                format_args!("`{name}` closes nothing"),
+            ) {
+                diagnostic.help(format_args!("nothing above it opens a `{{% {opening} %}}`"));
+            }
+        }
+    }
+
+    // ---- 3. a `{% load %}` of a library that is not there -------------------
+
+    fn unknown_libraries(&mut self) {
+        if !project::settings_are_authoritative(self.db, self.db.project()) {
+            return;
+        }
+
+        let unknown: Vec<_> = self
+            .index
+            .loads()
+            .iter()
+            .filter(|load| {
+                !project::tag_libraries(self.db, self.db.project())
+                    .iter()
+                    .any(|library| library.name == load.library)
+            })
+            .map(|load| (load.library.clone(), load.range))
+            .collect();
+
+        for (library, range) in unknown {
+            self.report(
+                &UNKNOWN_TEMPLATE_LIBRARY,
+                range,
+                format_args!("no tag library named `{library}`"),
+            );
+        }
+    }
+
+    // ---- 4, 5, 6. a tag or filter that is unknown or not loaded -------------
+
+    fn unknown_names(&mut self) {
+        if !self.libraries_known {
+            return;
+        }
+
+        let mut checked: Vec<(bool, CompactString, TextRange)> = Vec::new();
+
+        for construct in self.index.lexed().constructs() {
+            if construct.kind == ConstructKind::Comment {
+                continue;
+            }
+
+            if let Some(range) = construct.name.filter(|_| self.tag_is_checkable(construct)) {
+                checked.push((false, self.text(range).to_compact_string(), range));
+            }
+
+            checked.extend(
+                self.index
+                    .lexed()
+                    .construct_tokens(construct)
+                    .iter()
+                    .filter(|token| token.kind == TokenKind::FilterName)
+                    .map(|token| {
+                        (
+                            true,
+                            self.text(token.range).to_compact_string(),
+                            token.range,
+                        )
+                    }),
+            );
+        }
+
+        for (filter, name, range) in checked {
+            match self.provider(&name, filter) {
+                Provider::Loaded => {}
+                Provider::NotLoaded(library) => self.unloaded(&name, filter, &library, range),
+                Provider::Unknown => {
+                    let lint = if filter {
+                        &UNKNOWN_TEMPLATE_FILTER
+                    } else {
+                        &UNKNOWN_TEMPLATE_TAG
+                    };
+                    let kind = if filter { "filter" } else { "tag" };
+                    self.report(
+                        lint,
+                        range,
+                        format_args!("no template {kind} named `{name}`"),
+                    );
+                }
+            }
+        }
+    }
+
+    /// report a tag or filter whose library the template hasn't loaded, with the
+    /// `{% load %}` it needs as a fix
+    fn unloaded(&mut self, name: &str, filter: bool, library: &str, range: TextRange) {
+        let edit = load_edit_for(self.index, &self.loaded, Some(library))
+            .map(|edit| Fix::safe_edit(Edit::insertion(edit.text, edit.range.start())));
+        let kind = if filter { "filter" } else { "tag" };
+
+        if let Some(diagnostic) = self.report(
+            &UNLOADED_TEMPLATE_LIBRARY,
+            range,
+            format_args!("{kind} `{name}` needs `{{% load {library} %}}`"),
+        ) {
+            diagnostic.help(format_args!("add `{{% load {library} %}}`"));
+            diagnostic.set_optional_fix(edit);
+        }
+    }
+
+    /// whether a tag name is one this can decide anything about
+    ///
+    /// a tag that closed a block is a closing tag, and a closing tag is named by
+    /// the tag it closes rather than registered under a name of its own. a branch
+    /// is the same — `{% empty %}` is parsed by `{% for %}`, not registered — and
+    /// since a project's own block tag parses branches nothing here can enumerate,
+    /// every tag written directly inside one is left alone.
+    fn tag_is_checkable(&self, construct: &Construct) -> bool {
+        let Some(range) = construct.name else {
+            return false;
+        };
+        let name = self.text(range);
+
+        // a closing tag is named after the tag it closes rather than registered
+        // under a name of its own, so it is never one to look up
+        if name.starts_with(END_TAG_PREFIX) || BRANCH_TAGS.contains(&name) {
+            return false;
+        }
+
+        // the block the tag is written in, if any, decides whether its branches
+        // are knowable
+        self.index
+            .open_blocks_at(construct.range.start())
+            .first()
+            .is_none_or(|block| builtins::tag(&block.name).is_some())
+    }
+
+    /// where a tag or filter comes from, as far as this template is concerned
+    fn provider(&self, name: &str, filter: bool) -> Provider {
+        let registrations = project::registrations(self.db, self.db.project());
+
+        let table = if filter {
+            builtins::filter(name).map(|filter| filter.library)
+        } else {
+            builtins::tag(name).map(|tag| tag.library)
+        };
+
+        // the table's own answer is a fallback: which library django's own build
+        // registers a name in is read from the installed django where there is one
+        let django = registrations
+            .iter()
+            .find(|registration| {
+                registration.django
+                    && registration.name == name
+                    && (registration.kind == RegistrationKind::Filter) == filter
+            })
+            .map(|registration| Some(registration.library.as_str()));
+
+        if let Some(library) = django.or(table) {
+            return match library {
+                None => Provider::Loaded,
+                Some(library) if self.loaded.contains(&library.to_compact_string()) => {
+                    Provider::Loaded
+                }
+                Some(library) => Provider::NotLoaded(library.to_compact_string()),
+            };
+        }
+
+        let mut unloaded = None;
+        for registration in registrations.iter().filter(|registration| {
+            registration.name == name && (registration.kind == RegistrationKind::Filter) == filter
+        }) {
+            if self.loaded.contains(&registration.library) {
+                return Provider::Loaded;
+            }
+            unloaded.get_or_insert_with(|| registration.library.clone());
+        }
+
+        match unloaded {
+            Some(library) => Provider::NotLoaded(library),
+            None => Provider::Unknown,
+        }
+    }
+
+    // ---- 7. a template that is not there -----------------------------------
+
+    fn unresolved_templates(&mut self) {
+        if !project::settings_are_authoritative(self.db, self.db.project()) {
+            return;
+        }
+
+        let missing: Vec<_> = self
+            .index
+            .extends()
+            .into_iter()
+            .chain(self.index.includes())
+            .filter(|reference| project::resolve_template(self.db, &reference.name).is_none())
+            .map(|reference| (reference.name.clone(), reference.range))
+            .collect();
+
+        for (name, range) in missing {
+            if let Some(diagnostic) = self.report(
+                &UNRESOLVED_TEMPLATE,
+                range,
+                format_args!("no template named `{name}`"),
+            ) {
+                diagnostic.help(format_args!("create `{name}`"));
+            }
+        }
+    }
+
+    // ---- 8. a static file that is not there --------------------------------
+
+    fn unresolved_static_files(&mut self) {
+        if !project::settings_are_authoritative(self.db, self.db.project()) {
+            return;
+        }
+
+        let files = project::static_files(self.db, self.db.project());
+        let named: Vec<_> = self
+            .named_by(STATIC_TAG)
+            .into_iter()
+            .filter(|(name, _)| {
+                if files.iter().any(|file| file.name == *name) {
+                    return false;
+                }
+
+                // a name whose directory holds nothing at all is one this project
+                // builds rather than commits, and a source tree cannot answer for
+                // a file that isn't in it yet
+                let Some((directory, _)) = name.rsplit_once('/') else {
+                    return false;
+                };
+                files.iter().any(|file| {
+                    file.name
+                        .rsplit_once('/')
+                        .is_some_and(|(candidate, _)| candidate == directory)
+                })
+            })
+            .collect();
+
+        for (name, range) in named {
+            self.report(
+                &UNRESOLVED_STATIC_FILE,
+                range,
+                format_args!("no static file named `{name}`"),
+            );
+        }
+    }
+
+    // ---- 9, 10. a route that cannot be reversed ----------------------------
+
+    fn routes(&mut self) {
+        if !project::routes_are_authoritative(self.db, self.db.project()) {
+            return;
+        }
+
+        let mut unresolved = Vec::new();
+        let mut invalid = Vec::new();
+
+        for construct in self.index.lexed().constructs() {
+            if construct.name.map(|range| self.text(range)) != Some(URL_TAG) {
+                continue;
+            }
+
+            let arguments = self.arguments(construct);
+            let Some((name, range)) = arguments.first().and_then(|argument| {
+                let literal = argument.literal()?;
+                Some((
+                    self.string_value(literal)?,
+                    string_contents(self.source, literal.range),
+                ))
+            }) else {
+                continue;
+            };
+
+            let candidates: Vec<&UrlName> = project::url_names(self.db, self.db.project())
+                .iter()
+                .filter(|url| url.name == name)
+                .collect();
+
+            if candidates.is_empty() {
+                unresolved.push((name.to_compact_string(), range));
+                continue;
+            }
+
+            if let Some(complaint) = self.mismatch(&candidates, &arguments[1..]) {
+                invalid.push((name.to_compact_string(), complaint, construct.range));
+            }
+        }
+
+        for (name, range) in unresolved {
+            self.report(
+                &UNRESOLVED_ROUTE,
+                range,
+                format_args!("no route named `{name}`"),
+            );
+        }
+        for (name, complaint, range) in invalid {
+            self.report(
+                &INVALID_ROUTE_ARGUMENTS,
+                range,
+                format_args!("`{name}` {complaint}"),
+            );
+        }
+    }
+
+    /// why none of `candidates` takes `arguments`, when none of them does
+    ///
+    /// a route whose whole pattern isn't known takes anything, since what it
+    /// takes is exactly what is unknown.
+    fn mismatch(&self, candidates: &[&UrlName], arguments: &[Argument]) -> Option<String> {
+        let mut complaint = None;
+
+        for candidate in candidates {
+            let parameters = candidate.parameters()?;
+
+            match self.accepts(&parameters, arguments) {
+                Ok(()) => return None,
+                // the first candidate's complaint is the one reported: with one
+                // route of the name, which is the usual case, it is the only one
+                Err(reason) => complaint.get_or_insert(reason),
+            };
+        }
+
+        complaint
+    }
+
+    /// whether a route taking `parameters` accepts `arguments`
+    fn accepts(&self, parameters: &[Parameter], arguments: &[Argument]) -> Result<(), String> {
+        let (keyword, positional): (Vec<&Argument>, Vec<&Argument>) = arguments
+            .iter()
+            .partition(|argument| argument.name.is_some());
+
+        if !keyword.is_empty() && !positional.is_empty() {
+            return Err("cannot take positional and keyword arguments at once".to_string());
+        }
+
+        if keyword.is_empty() {
+            if positional.len() != parameters.len() {
+                return Err(format!(
+                    "takes {} argument{}, not {}",
+                    parameters.len(),
+                    if parameters.len() == 1 { "" } else { "s" },
+                    positional.len()
+                ));
+            }
+
+            for (parameter, argument) in parameters.iter().zip(positional) {
+                self.converts(parameter, argument)?;
+            }
+            return Ok(());
+        }
+
+        for argument in &keyword {
+            let name = argument.name.as_ref().expect("a keyword argument");
+            let Some(parameter) = parameters
+                .iter()
+                .find(|parameter| parameter.name == *name.0)
+            else {
+                return Err(format!("takes no argument named `{}`", name.0));
+            };
+            self.converts(parameter, argument)?;
+        }
+
+        if let Some(missing) = parameters.iter().find(|parameter| {
+            !keyword.iter().any(|argument| {
+                argument
+                    .name
+                    .as_ref()
+                    .is_some_and(|(name, _)| *name == parameter.name)
+            })
+        }) {
+            return Err(format!("needs an argument named `{}`", missing.name));
+        }
+
+        Ok(())
+    }
+
+    /// whether a literal argument is one the parameter's converter would match
+    ///
+    /// only a literal is answered for: a variable's value is not known here, and
+    /// django would only find out at render time either.
+    fn converts(&self, parameter: &Parameter, argument: &Argument) -> Result<(), String> {
+        let Some(token) = argument.literal() else {
+            return Ok(());
+        };
+        let Some(converter) = parameter.converter else {
+            return Ok(());
+        };
+        let value = match token.kind {
+            TokenKind::String => self.string_value(token).unwrap_or_default(),
+            TokenKind::Number => self.text(token.range),
+            _ => return Ok(()),
+        };
+
+        if converter.matches(value) {
+            return Ok(());
+        }
+
+        Err(format!(
+            "takes `{}` through `{}`, which `{value}` is not",
+            parameter.name,
+            converter.name()
+        ))
+    }
+
+    // ---- 11. a block no ancestor declares ----------------------------------
+
+    fn unknown_blocks(&mut self) {
+        if self.index.extends().is_none() {
+            return;
+        }
+
+        let chain = ancestors(self.db, self.file, self.index);
+        // a chain that stops before a template with no parent of its own is one
+        // whose blocks have not all been seen
+        let complete = chain
+            .last()
+            .is_some_and(|(_, ancestor)| ancestor.extends().is_none());
+        if !complete {
+            return;
+        }
+
+        let declared: FxHashSet<CompactString> = chain
+            .iter()
+            .flat_map(|(_, ancestor)| ancestor.blocks())
+            .map(|block| block.name.clone())
+            .collect();
+
+        let unknown: Vec<_> = self
+            .index
+            .blocks()
+            .iter()
+            .filter(|block| !declared.contains(&block.name))
+            .filter(|block| self.is_top_level(block.name_range))
+            .map(|block| (block.name.clone(), block.name_range))
+            .collect();
+
+        for (name, range) in unknown {
+            if let Some(diagnostic) = self.report(
+                &UNKNOWN_TEMPLATE_BLOCK,
+                range,
+                format_args!("no ancestor template declares `{name}`"),
+            ) {
+                diagnostic.help("the block is never rendered");
+            }
+        }
+    }
+
+    /// whether `offset` is outside every `{% block %}` and `{% partialdef %}`
+    ///
+    /// a block nested inside one is rendered as part of it, so it overrides
+    /// nothing and needs nothing above it to override.
+    fn is_top_level(&self, range: TextRange) -> bool {
+        !self.index.spans().iter().any(|span| {
+            matches!(span.name.as_str(), "block" | "partialdef")
+                && span.body_range.contains(range.start())
+        })
+    }
+
+    // ---- 12. a lookup landing on a method that needs arguments -------------
+
+    fn members_needing_arguments(&mut self) {
+        let mut found = Vec::new();
+
+        for construct in self.index.lexed().constructs() {
+            if construct.kind != ConstructKind::Variable {
+                continue;
+            }
+
+            for path in self.paths(construct) {
+                let segments: Vec<&str> = path.iter().map(|token| self.text(token.range)).collect();
+
+                for length in 1..segments.len() {
+                    let Some(ty) = resolve::path_type(
+                        self.db,
+                        self.file,
+                        self.index,
+                        self.source,
+                        construct.range.start(),
+                        &segments[..length],
+                    ) else {
+                        break;
+                    };
+                    let Some(member) = resolve::uncalled_member_type(self.db, ty, segments[length])
+                    else {
+                        break;
+                    };
+
+                    if callable_needs_arguments(self.db, member) {
+                        found.push((segments[length].to_compact_string(), path[length].range));
+                        break;
+                    }
+                }
+            }
+        }
+
+        for (name, range) in found {
+            if let Some(diagnostic) = self.report(
+                &TEMPLATE_MEMBER_NEEDS_ARGUMENTS,
+                range,
+                format_args!("`{name}` needs arguments"),
+            ) {
+                diagnostic.help("django renders nothing for a member it cannot call");
+            }
+        }
+    }
+
+    // ---- reading a construct's arguments -----------------------------------
+
+    /// the first argument of every `{% tag %}` of this name that writes a string
+    fn named_by(&self, tag: &str) -> Vec<(CompactString, TextRange)> {
+        self.index
+            .lexed()
+            .constructs()
+            .iter()
+            .filter(|construct| construct.name.map(|range| self.text(range)) == Some(tag))
+            .filter_map(|construct| {
+                let literal = *self.arguments(construct).first()?.literal()?;
+                Some((
+                    self.string_value(&literal)?.to_compact_string(),
+                    string_contents(self.source, literal.range),
+                ))
+            })
+            .collect()
+    }
+
+    /// a tag's arguments, its name and its trailing `as …` dropped
+    fn arguments(&self, construct: &Construct) -> Vec<Argument> {
+        let tokens = self.index.lexed().inner_tokens(construct);
+        let start = usize::from(
+            tokens
+                .first()
+                .is_some_and(|token| token.kind == TokenKind::TagName),
+        );
+
+        let mut arguments = Vec::new();
+        let mut index = start;
+
+        while let Some(token) = tokens.get(index) {
+            match token.kind {
+                // everything after an `as` names the tag's result, not its input
+                TokenKind::Keyword if self.text(token.range) == "as" => break,
+                TokenKind::KeywordArgument => {
+                    // the name, then the `=`, then the value
+                    let value = tokens.get(index + 2).copied();
+                    arguments.push(Argument {
+                        name: Some((self.text(token.range).to_compact_string(), token.range)),
+                        value,
+                    });
+                    index = end_of_value(self.source, tokens, index + 2);
+                }
+                TokenKind::String
+                | TokenKind::Number
+                | TokenKind::Variable
+                | TokenKind::BuiltinConstant => {
+                    arguments.push(Argument {
+                        name: None,
+                        value: Some(*token),
+                    });
+                    index = end_of_value(self.source, tokens, index);
+                }
+                _ => index += 1,
+            }
+        }
+
+        arguments
+    }
+
+    /// every dotted path written in a construct, as its tokens
+    fn paths(&self, construct: &Construct) -> Vec<Vec<Token>> {
+        let tokens = self.index.lexed().inner_tokens(construct);
+        let mut paths: Vec<Vec<Token>> = Vec::new();
+
+        for (index, token) in tokens.iter().enumerate() {
+            match token.kind {
+                TokenKind::Variable => paths.push(vec![*token]),
+                TokenKind::Attribute => {
+                    // an attribute belongs to the path before it only if a `.`
+                    // joins the two
+                    let joined = tokens
+                        .get(index - 1)
+                        .is_some_and(|previous| self.text(previous.range) == ".");
+                    if let Some(path) = paths.last_mut().filter(|_| joined) {
+                        path.push(*token);
+                    }
+                }
+                _ => {}
+            }
+        }
+
+        paths
+    }
+
+    /// the contents of a string literal token
+    fn string_value(&self, token: &Token) -> Option<&str> {
+        (token.kind == TokenKind::String)
+            .then(|| self.text(string_contents(self.source, token.range)))
+    }
+}
+
+/// the quick fixes offered for a template diagnostic at `range`
+///
+/// the suppression is always offered — every rule has to be silenceable — and a
+/// reference to a template that isn't there is offered the one action that fixes
+/// it, since the template roots are known and so the destination is too.
+pub(crate) fn code_actions(
+    db: &dyn Db,
+    file: File,
+    index: &TemplateIndex,
+    source: &str,
+    range: TextRange,
+    lint: LintId,
+) -> Vec<QuickFix> {
+    let mut actions = Vec::new();
+
+    if lint == LintId::of(&UNRESOLVED_TEMPLATE)
+        && let Some(destination) = missing_template(db, file, index, source, range)
+    {
+        actions.push(QuickFix {
+            title: format!("Create `{}`", &source[range]),
+            edits: Vec::new(),
+            preferred: true,
+            create: Some(destination),
+        });
+    }
+
+    actions.push(QuickFix {
+        title: format!("Ignore '{}' for this line", lint.name()),
+        edits: vec![Edit::insertion(
+            format!(" {{# ty: ignore[{}] #}}", lint.name()),
+            line_end(source, range.start()),
+        )],
+        preferred: false,
+        create: None,
+    });
+
+    actions
+}
+
+/// where the template a reference at `range` names ought to go
+///
+/// the app whose template writes the reference is the app the new template
+/// belongs to, so it goes in that app's own `templates` directory — beside the
+/// file that wanted it, under the name it wanted.
+fn missing_template(
+    db: &dyn Db,
+    file: File,
+    index: &TemplateIndex,
+    source: &str,
+    range: TextRange,
+) -> Option<SystemPathBuf> {
+    let name = index
+        .extends()
+        .into_iter()
+        .chain(index.includes())
+        .find(|reference| reference.range == range)?;
+
+    let _ = source;
+    let root = file
+        .path(db)
+        .as_system_path()?
+        .ancestors()
+        .find(|ancestor| ancestor.file_name() == Some(TEMPLATE_DIRECTORY))?;
+
+    Some(root.join(name.name.as_str()))
+}
+
+/// the end of the line `offset` is on, its terminator excluded
+fn line_end(source: &str, offset: TextSize) -> TextSize {
+    let offset = usize::from(offset);
+    let end = source[offset..]
+        .find('\n')
+        .map_or(source.len(), |index| offset + index);
+    let end = if source[..end].ends_with('\r') {
+        end - 1
+    } else {
+        end
+    };
+
+    TextSize::try_from(end).unwrap_or_default()
+}
+
+/// where a template can get a tag or a filter from
+enum Provider {
+    /// this template has it
+    Loaded,
+    /// the project has it, in a library this template hasn't loaded
+    NotLoaded(CompactString),
+    /// nothing the project can reach registers it
+    Unknown,
+}
+
+/// one argument written in a tag
+struct Argument {
+    /// the `name=` a keyword argument is written with
+    name: Option<(CompactString, TextRange)>,
+    /// the first token of the argument's value
+    value: Option<Token>,
+}
+
+impl Argument {
+    /// the argument's value, when it is written out rather than computed
+    fn literal(&self) -> Option<&Token> {
+        self.value
+            .as_ref()
+            .filter(|token| matches!(token.kind, TokenKind::String | TokenKind::Number))
+    }
+}
+
+/// the index just past the value beginning at `index`
+///
+/// a value is a dotted path with any number of filters applied to it, and each
+/// filter may take an argument of its own — all of it one argument as far as the
+/// tag is concerned.
+fn end_of_value(source: &str, tokens: &[Token], index: usize) -> usize {
+    let mut index = index + 1;
+
+    while let (Some(joiner), Some(_)) = (tokens.get(index), tokens.get(index + 1)) {
+        if joiner.kind != TokenKind::Operator || !matches!(&source[joiner.range], "." | "|" | ":") {
+            break;
+        }
+        index += 2;
+    }
+
+    index
+}
+
+/// the names a builtin tag parses as part of its own block rather than
+/// registering
+///
+/// `{% empty %}` is not a tag django could look up; it is a word `{% for %}`
+/// reads. the union over every builtin is used rather than the enclosing block's
+/// own list, so that a branch written under the wrong tag is left to django to
+/// complain about rather than reported as a tag that doesn't exist.
+const BRANCH_TAGS: &[&str] = &["elif", "else", "empty", "plural"];
+
+/// whether `name` is a tag django knows opens a block
+fn opens_a_block(db: &dyn Db, name: &str) -> bool {
+    builtins::tag(name).is_some_and(|tag| tag.closed_by.is_some())
+        || project::registrations(db, db.project())
+            .iter()
+            .any(|registration| {
+                registration.name == name
+                    && registration.kind == RegistrationKind::Tag { block: true }
+            })
+}
+
+/// whether `name` is a tag django knows closes a block
+fn closes_a_block(db: &dyn Db, name: &str) -> bool {
+    name.strip_prefix(END_TAG_PREFIX)
+        .is_some_and(|opening| opens_a_block(db, opening))
+}
+
+/// one argument a route pattern takes
+struct Parameter {
+    name: CompactString,
+    /// the converter django puts the argument through, where it is one of its own
+    converter: Option<Converter>,
+}
+
+/// the path converters django ships
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+enum Converter {
+    Str,
+    Int,
+    Slug,
+    Uuid,
+    Path,
+}
+
+impl Converter {
+    fn of(name: &str) -> Option<Self> {
+        match name {
+            "str" => Some(Self::Str),
+            "int" => Some(Self::Int),
+            "slug" => Some(Self::Slug),
+            "uuid" => Some(Self::Uuid),
+            "path" => Some(Self::Path),
+            _ => None,
+        }
+    }
+
+    fn name(self) -> &'static str {
+        match self {
+            Self::Str => "str",
+            Self::Int => "int",
+            Self::Slug => "slug",
+            Self::Uuid => "uuid",
+            Self::Path => "path",
+        }
+    }
+
+    /// whether a value written out in the template is one this would match
+    fn matches(self, value: &str) -> bool {
+        match self {
+            Self::Str => !value.is_empty() && !value.contains('/'),
+            Self::Int => !value.is_empty() && value.bytes().all(|byte| byte.is_ascii_digit()),
+            Self::Slug => {
+                !value.is_empty()
+                    && value
+                        .bytes()
+                        .all(|byte| byte.is_ascii_alphanumeric() || byte == b'-' || byte == b'_')
+            }
+            Self::Uuid => {
+                let groups: Vec<&str> = value.split('-').collect();
+                groups.len() == 5
+                    && [8, 4, 4, 4, 12]
+                        == *groups.iter().map(|group| group.len()).collect::<Vec<_>>()
+                    && value
+                        .bytes()
+                        .all(|byte| byte.is_ascii_hexdigit() || byte == b'-')
+            }
+            Self::Path => !value.is_empty(),
+        }
+    }
+}
+
+impl UrlName {
+    /// the arguments this route takes, or `None` where they cannot be read
+    fn parameters(&self) -> Option<Vec<Parameter>> {
+        self.exact
+            .then_some(self.route.as_deref()?)
+            .and_then(parameters_of)
+    }
+}
+
+/// the arguments a route pattern names
+///
+/// django writes them two ways: `path()` takes `<converter:name>` and
+/// `re_path()` takes a named group. a pattern with an *unnamed* group takes
+/// arguments nothing can name, so it answers nothing rather than too few.
+fn parameters_of(pattern: &str) -> Option<Vec<Parameter>> {
+    let mut parameters = Vec::new();
+    let mut rest = pattern;
+
+    while let Some(index) = rest.find(['<', '(']) {
+        let after = &rest[index..];
+
+        if let Some(after) = after.strip_prefix('<') {
+            let (declaration, tail) = after.split_once('>')?;
+            let (converter, name) = match declaration.split_once(':') {
+                Some((converter, name)) => (Converter::of(converter), name),
+                None => (Some(Converter::Str), declaration),
+            };
+            parameters.push(Parameter {
+                name: name.to_compact_string(),
+                converter,
+            });
+            rest = tail;
+            continue;
+        }
+
+        let after = after.strip_prefix('(').unwrap_or(after);
+        if let Some(after) = after.strip_prefix("?P<") {
+            let (name, tail) = after.split_once('>')?;
+            parameters.push(Parameter {
+                name: name.to_compact_string(),
+                // what a regex group matches is not one of django's converters,
+                // so a literal written against it is not checked
+                converter: None,
+            });
+            rest = tail;
+            continue;
+        }
+
+        // a group that captures without naming takes a positional argument this
+        // has no name for, so the pattern is one to say nothing about
+        if !after.starts_with("?:") && !after.starts_with("?=") && !after.starts_with("?!") {
+            return None;
+        }
+        rest = after;
+    }
+
+    Some(parameters)
+}
+
+/// the `{# ty: ignore #}` comments a template writes
+///
+/// a template has no `# type: ignore` to borrow, and its comment syntax is the
+/// natural place to put one: `{# ty: ignore #}` silences every diagnostic on its
+/// line, `{# ty: ignore[unknown-template-tag] #}` only the rules it names, and a
+/// comment written on a line of its own covers the line below it as well — which
+/// is what a tag occupying its whole line needs.
+#[derive(Debug, Default)]
+struct Suppressions {
+    entries: Vec<Suppression>,
+}
+
+#[derive(Debug)]
+struct Suppression {
+    /// the line the comment is on
+    line: OneIndexed,
+    /// whether the comment stands alone, and so covers the line below it too
+    alone: bool,
+    /// the rules it names, or nothing for a blanket one
+    rules: Vec<CompactString>,
+}
+
+/// what a suppression comment is written with
+const SUPPRESSION_PREFIX: &str = "ty: ignore";
+
+impl Suppressions {
+    fn of(index: &TemplateIndex, source: &str) -> Self {
+        let mut entries = Vec::new();
+
+        for construct in index.lexed().constructs() {
+            if construct.kind != ConstructKind::Comment {
+                continue;
+            }
+
+            let body = source[construct.range]
+                .trim_start_matches("{#")
+                .trim_end_matches("#}")
+                .trim();
+            let Some(rules) = body.strip_prefix(SUPPRESSION_PREFIX) else {
+                continue;
+            };
+            let rules = match rules.trim() {
+                "" => Vec::new(),
+                rules => {
+                    let Some(named) = rules
+                        .strip_prefix('[')
+                        .and_then(|rules| rules.strip_suffix(']'))
+                    else {
+                        continue;
+                    };
+                    named
+                        .split(',')
+                        .map(|rule| rule.trim().to_compact_string())
+                        .filter(|rule| !rule.is_empty())
+                        .collect()
+                }
+            };
+
+            let line_start = source[..usize::from(construct.range.start())]
+                .rfind('\n')
+                .map_or(0, |index| index + 1);
+            let line_end = source[usize::from(construct.range.end())..]
+                .find('\n')
+                .map_or(source.len(), |index| {
+                    usize::from(construct.range.end()) + index
+                });
+
+            let alone = source[line_start..usize::from(construct.range.start())]
+                .trim()
+                .is_empty()
+                && source[usize::from(construct.range.end())..line_end]
+                    .trim()
+                    .is_empty();
+
+            entries.push(Suppression {
+                line: line_of(source, construct.range.start()),
+                alone,
+                rules,
+            });
+        }
+
+        Self { entries }
+    }
+
+    fn covers(&self, lint: &'static LintMetadata, line: OneIndexed) -> bool {
+        self.entries.iter().any(|suppression| {
+            let covered = suppression.line == line
+                || (suppression.alone && suppression.line.saturating_add(1) == line);
+
+            covered
+                && (suppression.rules.is_empty()
+                    || suppression
+                        .rules
+                        .iter()
+                        .any(|rule| rule.as_str() == &*lint.name()))
+        })
+    }
+}
+
+/// the one-indexed line `offset` is on
+fn line_of(source: &str, offset: TextSize) -> OneIndexed {
+    OneIndexed::from_zero_indexed(source[..usize::from(offset)].matches('\n').count())
+}
+
+#[cfg(test)]
+mod tests {
+    use ruff_text_size::Ranged;
+
+    use crate::django_template::tests::TemplateTest;
+
+    /// a whole django project: a settings module the convention finds, an app
+    /// with a tag library, models, a view, a url tree and a base template
+    ///
+    /// django is installed beside it rather than in it, since that is what makes
+    /// `{% load static %}` and `{% load humanize %}` resolve — and what makes the
+    /// indexes authoritative, which every check below depends on.
+    fn project(template: &str) -> TemplateTest {
+        TemplateTest::with_site_packages(
+            &[
+                (
+                    "manage.py",
+                    "
+                    import os
+
+                    os.environ.setdefault('DJANGO_SETTINGS_MODULE', 'project.settings')
+                    ",
+                ),
+                ("project/__init__.py", ""),
+                (
+                    "project/settings.py",
+                    "
+                    INSTALLED_APPS = ['django.contrib.humanize', 'blog']
+
+                    TEMPLATES = [{'DIRS': [], 'APP_DIRS': True, 'OPTIONS': {}}]
+
+                    ROOT_URLCONF = 'project.urls'
+                    ",
+                ),
+                (
+                    "project/urls.py",
+                    "
+                    from django.urls import include, path
+
+                    urlpatterns = [path('blog/', include('blog.urls'))]
+                    ",
+                ),
+                ("blog/__init__.py", ""),
+                (
+                    "blog/models.py",
+                    "
+                    class Book:
+                        title: str
+
+                        def summary(self) -> str:
+                            return self.title
+
+                        def excerpt(self, length: int) -> str:
+                            return self.title[:length]
+                    ",
+                ),
+                (
+                    "blog/views.py",
+                    "
+                    from blog.models import Book
+
+
+                    def post(request):
+                        return render(request, 'blog/post.html', {'book': Book()})
+                    ",
+                ),
+                (
+                    "blog/urls.py",
+                    "
+                    from django.urls import path
+
+                    app_name = 'blog'
+
+                    urlpatterns = [
+                        path('', index, name='index'),
+                        path('<int:pk>/', detail, name='detail'),
+                        path('<slug:slug>/<int:page>/', paged, name='paged'),
+                    ]
+                    ",
+                ),
+                ("blog/templatetags/__init__.py", ""),
+                (
+                    "blog/templatetags/blog_extras.py",
+                    "
+                    from django import template
+
+                    register = template.Library()
+
+                    @register.filter
+                    def shout(value):
+                        return value
+
+                    @register.simple_tag
+                    def badge():
+                        return ''
+
+                    @register.simple_block_tag
+                    def box(content):
+                        return content
+                    ",
+                ),
+                (
+                    "blog/templates/blog/base.html",
+                    "{% block content %}{% endblock %}{% block footer %}{% endblock %}",
+                ),
+                ("blog/static/blog/site.css", "body {}"),
+                ("blog/templates/blog/post.html", template),
+            ],
+            &[
+                ("django/__init__.py", ""),
+                ("django/templatetags/__init__.py", ""),
+                (
+                    "django/templatetags/static.py",
+                    "
+                    from django.template import Library
+
+                    register = Library()
+
+                    @register.simple_tag
+                    def static(path):
+                        return path
+                    ",
+                ),
+                ("django/contrib/__init__.py", ""),
+                ("django/contrib/humanize/__init__.py", ""),
+                ("django/contrib/humanize/templatetags/__init__.py", ""),
+                (
+                    "django/contrib/humanize/templatetags/humanize.py",
+                    "
+                    from django.template import Library
+
+                    register = Library()
+
+                    @register.filter
+                    def intcomma(value):
+                        return value
+                    ",
+                ),
+            ],
+        )
+    }
+
+    /// the project's templates with nothing wrong with them
+    #[test]
+    fn a_correct_template_reports_nothing() {
+        let test = project(
+            "{% extends 'blog/base.html' %}\n\
+             {% load blog_extras static %}\n\
+             {% block content %}\n\
+             <img src=\"{% static 'blog/site.css' %}\">\n\
+             <a href=\"{% url 'blog:detail' pk=book.pk %}\">{{ book.title|shout|upper }}</a>\n\
+             {% for word in book.summary %}{{ word }}{% empty %}none{% endfor %}\n\
+             {% if book %}{{ book.summary }}{% else %}?{% endif %}\n\
+             {% endblock %}\n",
+        );
+
+        assert_eq!(test.diagnostics(), Vec::<String>::new());
+    }
+
+    #[test]
+    fn an_unclosed_block_tag_is_reported() {
+        assert_eq!(
+            project("{% if book %}\n<p>hi</p>\n").diagnostics(),
+            ["unclosed-template-block Error: unclosed `if` [{% if book %}]"]
+        );
+    }
+
+    #[test]
+    fn a_closed_block_tag_is_not_reported() {
+        assert!(
+            project("{% if book %}<p>hi</p>{% endif %}\n")
+                .diagnostics()
+                .is_empty()
+        );
+    }
+
+    #[test]
+    fn an_unclosed_block_tag_of_the_projects_own_is_reported() {
+        assert_eq!(
+            project("{% load blog_extras %}\n{% box %}a{% endbox %}\n{% box %}b\n").diagnostics(),
+            ["unclosed-template-block Error: unclosed `box` [{% box %}]"]
+        );
+    }
+
+    #[test]
+    fn a_tag_nothing_says_opens_a_block_is_not_reported_unclosed() {
+        // `{% modal %}` is nobody's registered block tag; that this file pairs one
+        // of them with an `{% endmodal %}` is not enough to call the other wrong.
+        // that the tag isn't registered at all is a different complaint
+        assert_eq!(
+            project("{% modal %}a{% endmodal %}\n{% modal %}b\n").diagnostics(),
+            [
+                "unknown-template-tag Error: no template tag named `modal` [modal]",
+                "unknown-template-tag Error: no template tag named `modal` [modal]",
+            ]
+        );
+    }
+
+    #[test]
+    fn a_closing_tag_that_closes_nothing_is_reported() {
+        assert_eq!(
+            project("{% for book in books %}a{% endwith %}{% endfor %}\n").diagnostics(),
+            ["unmatched-template-close Error: `endwith` closes nothing [{% endwith %}]"]
+        );
+    }
+
+    #[test]
+    fn a_closing_tag_that_closes_something_is_not_reported() {
+        assert!(
+            project("{% for book in books %}a{% endfor %}\n")
+                .diagnostics()
+                .is_empty()
+        );
+    }
+
+    #[test]
+    fn a_closing_tag_of_an_unknown_block_tag_is_not_reported() {
+        assert!(project("{% endmodal %}\n").diagnostics().is_empty());
+    }
+
+    #[test]
+    fn a_load_of_a_library_that_is_not_there_is_reported() {
+        assert_eq!(
+            project("{% load blog_xtras %}\n").diagnostics(),
+            ["unknown-template-library Error: no tag library named `blog_xtras` [blog_xtras]"]
+        );
+    }
+
+    #[test]
+    fn a_load_of_a_library_that_is_there_is_not_reported() {
+        assert!(
+            project("{% load blog_extras static humanize %}\n")
+                .diagnostics()
+                .is_empty()
+        );
+    }
+
+    #[test]
+    fn a_tag_nothing_registers_is_reported() {
+        assert_eq!(
+            project("{% iff book %}\n").diagnostics(),
+            ["unknown-template-tag Error: no template tag named `iff` [iff]"]
+        );
+    }
+
+    #[test]
+    fn a_branch_of_a_builtin_block_is_not_reported_as_a_tag() {
+        assert!(
+            project(
+                "{% if book %}a{% else %}b{% endif %}{% for x in y %}a{% empty %}b{% endfor %}"
+            )
+            .diagnostics()
+            .is_empty()
+        );
+    }
+
+    #[test]
+    fn a_tag_written_inside_a_block_tag_nobody_knows_is_not_reported() {
+        // whatever `{% modal %}` parses between its own tags is `{% modal %}`'s
+        // business, and nothing here can enumerate it — only the opening tag,
+        // which is written outside any such block, is answered for
+        assert_eq!(
+            project("{% modal %}{% modal_header %}{% endmodal %}").diagnostics(),
+            ["unknown-template-tag Error: no template tag named `modal` [modal]"]
+        );
+    }
+
+    #[test]
+    fn a_filter_nothing_registers_is_reported() {
+        assert_eq!(
+            project("{{ book.title|uppercase }}\n").diagnostics(),
+            ["unknown-template-filter Error: no template filter named `uppercase` [uppercase]"]
+        );
+    }
+
+    #[test]
+    fn a_builtin_filter_is_not_reported() {
+        assert!(
+            project("{{ book.title|upper|default:'x' }}\n")
+                .diagnostics()
+                .is_empty()
+        );
+    }
+
+    #[test]
+    fn a_tag_whose_library_is_not_loaded_is_reported() {
+        assert_eq!(
+            project("{% static 'blog/site.css' %}\n").diagnostics(),
+            ["unloaded-template-library Error: tag `static` needs `{% load static %}` [static]"]
+        );
+    }
+
+    #[test]
+    fn a_filter_whose_library_is_not_loaded_is_reported() {
+        assert_eq!(
+            project("{{ book.title|shout }}\n").diagnostics(),
+            [
+                "unloaded-template-library Error: filter `shout` needs `{% load blog_extras %}` \
+                 [shout]"
+            ]
+        );
+    }
+
+    #[test]
+    fn an_unloaded_library_carries_the_load_it_needs_as_a_fix() {
+        let test = project("{% extends 'blog/base.html' %}\n{{ book.title|shout }}\n");
+        let diagnostics = crate::django_template::django_template_diagnostics(&test.db, test.file);
+
+        let fix = diagnostics[0].fix().expect("a fix");
+        let edit = fix.edits().first().expect("an edit");
+
+        assert_eq!(edit.content(), Some("\n{% load blog_extras %}"));
+        assert_eq!(
+            u32::from(edit.start()),
+            30,
+            "the load goes below the `{{% extends %}}`, which has to stay first"
+        );
+    }
+
+    #[test]
+    fn a_loaded_library_is_not_reported() {
+        assert!(
+            project(
+                "{% load blog_extras static %}{% static 'blog/site.css' %}{{ book.title|shout }}"
+            )
+            .diagnostics()
+            .is_empty()
+        );
+    }
+
+    #[test]
+    fn a_library_the_settings_load_into_every_template_needs_no_load() {
+        // this is the same template as above with the `{% load %}` taken away, and
+        // it is correct because `OPTIONS['builtins']` says so
+        let test = TemplateTest::with_site_packages(
+            &[
+                (
+                    "manage.py",
+                    "
+                    import os
+
+                    os.environ.setdefault('DJANGO_SETTINGS_MODULE', 'project.settings')
+                    ",
+                ),
+                ("project/__init__.py", ""),
+                (
+                    "project/settings.py",
+                    "
+                    INSTALLED_APPS = []
+
+                    TEMPLATES = [
+                        {
+                            'APP_DIRS': True,
+                            'OPTIONS': {'builtins': ['django.templatetags.static']},
+                        }
+                    ]
+                    ",
+                ),
+                ("blog/__init__.py", ""),
+                (
+                    "blog/templates/blog/post.html",
+                    "{% static 'blog/site.css' %}",
+                ),
+            ],
+            &[
+                ("django/__init__.py", ""),
+                ("django/templatetags/__init__.py", ""),
+                (
+                    "django/templatetags/static.py",
+                    "
+                    register = Library()
+
+                    @register.simple_tag
+                    def static(path):
+                        return path
+                    ",
+                ),
+            ],
+        );
+
+        assert!(test.diagnostics().is_empty());
+    }
+
+    #[test]
+    fn an_extends_of_a_template_that_is_not_there_is_reported() {
+        assert_eq!(
+            project("{% extends 'blog/bass.html' %}\n").diagnostics(),
+            ["unresolved-template Error: no template named `blog/bass.html` [blog/bass.html]"]
+        );
+    }
+
+    #[test]
+    fn an_include_of_a_template_that_is_not_there_is_reported() {
+        assert_eq!(
+            project("{% include 'blog/card.html' %}\n").diagnostics(),
+            ["unresolved-template Error: no template named `blog/card.html` [blog/card.html]"]
+        );
+    }
+
+    #[test]
+    fn a_reference_to_a_template_that_is_there_is_not_reported() {
+        assert!(
+            project("{% extends 'blog/base.html' %}\n")
+                .diagnostics()
+                .is_empty()
+        );
+    }
+
+    #[test]
+    fn a_static_file_that_is_not_there_is_reported() {
+        assert_eq!(
+            project("{% load static %}{% static 'blog/sight.css' %}\n").diagnostics(),
+            [
+                "unresolved-static-file Warning: no static file named `blog/sight.css` \
+                 [blog/sight.css]"
+            ]
+        );
+    }
+
+    #[test]
+    fn a_static_file_that_is_there_is_not_reported() {
+        assert!(
+            project("{% load static %}{% static 'blog/site.css' %}\n")
+                .diagnostics()
+                .is_empty()
+        );
+    }
+
+    #[test]
+    fn a_static_file_in_a_directory_the_source_tree_has_nothing_in_is_not_reported() {
+        // `bundles/` is what a build writes into `static/`, and a source tree
+        // cannot answer for a file that isn't in it yet
+        assert!(
+            project("{% load static %}{% static 'bundles/app.js' %}\n")
+                .diagnostics()
+                .is_empty()
+        );
+    }
+
+    #[test]
+    fn a_url_naming_a_route_that_is_not_there_is_reported() {
+        assert_eq!(
+            project("{% url 'blog:missing' %}\n").diagnostics(),
+            ["unresolved-route Error: no route named `blog:missing` [blog:missing]"]
+        );
+    }
+
+    #[test]
+    fn a_url_naming_a_route_that_is_there_is_not_reported() {
+        assert!(
+            project("{% url 'blog:index' %}{% url 'blog:detail' 1 %}\n")
+                .diagnostics()
+                .is_empty()
+        );
+    }
+
+    #[test]
+    fn a_url_missing_an_argument_is_reported() {
+        assert_eq!(
+            project("{% url 'blog:detail' %}\n").diagnostics(),
+            [
+                "invalid-route-arguments Error: `blog:detail` takes 1 argument, not 0 \
+                 [{% url 'blog:detail' %}]"
+            ]
+        );
+    }
+
+    #[test]
+    fn a_url_with_an_argument_the_route_does_not_name_is_reported() {
+        assert_eq!(
+            project("{% url 'blog:detail' slug='x' %}\n").diagnostics(),
+            [
+                "invalid-route-arguments Error: `blog:detail` takes no argument named `slug` \
+                 [{% url 'blog:detail' slug='x' %}]"
+            ]
+        );
+    }
+
+    #[test]
+    fn a_url_whose_literal_the_converter_would_reject_is_reported() {
+        assert_eq!(
+            project("{% url 'blog:detail' pk='abc' %}\n").diagnostics(),
+            [
+                "invalid-route-arguments Error: `blog:detail` takes `pk` through `int`, which \
+                 `abc` is not [{% url 'blog:detail' pk='abc' %}]"
+            ]
+        );
+    }
+
+    #[test]
+    fn a_url_whose_arguments_the_route_takes_is_not_reported() {
+        assert!(
+            project(
+                "{% url 'blog:detail' pk=1 %}{% url 'blog:paged' slug='a' page=2 %}\
+                 {% url 'blog:paged' 'a' 2 %}{% url 'blog:detail' book.pk %}\n"
+            )
+            .diagnostics()
+            .is_empty()
+        );
+    }
+
+    #[test]
+    fn a_block_no_ancestor_declares_is_reported() {
+        assert_eq!(
+            project("{% extends 'blog/base.html' %}{% block sidebar %}a{% endblock %}\n")
+                .diagnostics(),
+            ["unknown-template-block Warning: no ancestor template declares `sidebar` [sidebar]"]
+        );
+    }
+
+    #[test]
+    fn a_block_an_ancestor_declares_is_not_reported() {
+        assert!(
+            project("{% extends 'blog/base.html' %}{% block content %}a{% endblock %}\n")
+                .diagnostics()
+                .is_empty()
+        );
+    }
+
+    #[test]
+    fn a_block_nested_inside_an_overriding_one_is_not_reported() {
+        // django renders it as part of the block around it, so nothing above has
+        // to declare it
+        assert!(
+            project(
+                "{% extends 'blog/base.html' %}\
+                 {% block content %}{% block inner %}a{% endblock %}{% endblock %}\n"
+            )
+            .diagnostics()
+            .is_empty()
+        );
+    }
+
+    #[test]
+    fn a_block_in_a_template_that_extends_nothing_is_not_reported() {
+        assert!(
+            project("{% block anything %}a{% endblock %}\n")
+                .diagnostics()
+                .is_empty()
+        );
+    }
+
+    #[test]
+    fn a_member_that_needs_arguments_is_reported() {
+        assert_eq!(
+            project("{{ book.excerpt }}\n").diagnostics(),
+            ["template-member-needs-arguments Warning: `excerpt` needs arguments [excerpt]"]
+        );
+    }
+
+    #[test]
+    fn a_member_that_needs_no_arguments_is_not_reported() {
+        assert!(
+            project("{{ book.summary }}{{ book.title }}\n")
+                .diagnostics()
+                .is_empty()
+        );
+    }
+
+    #[test]
+    fn a_suppression_on_the_same_line_silences_the_line() {
+        assert!(
+            project("{% iff book %} {# ty: ignore #}\n")
+                .diagnostics()
+                .is_empty()
+        );
+    }
+
+    #[test]
+    fn a_suppression_on_its_own_line_silences_the_line_below_it() {
+        assert!(
+            project("{# ty: ignore #}\n{% iff book %}\n")
+                .diagnostics()
+                .is_empty()
+        );
+    }
+
+    #[test]
+    fn a_suppression_naming_rules_silences_only_those() {
+        assert_eq!(
+            project("{# ty: ignore[unknown-template-filter] #}\n{% iff book %}\n").diagnostics(),
+            ["unknown-template-tag Error: no template tag named `iff` [iff]"],
+            "a rule the comment doesn't name is still reported"
+        );
+        assert!(
+            project("{# ty: ignore[unknown-template-tag] #}\n{% iff book %}\n")
+                .diagnostics()
+                .is_empty()
+        );
+    }
+
+    #[test]
+    fn a_suppression_with_something_beside_it_covers_only_its_own_line() {
+        assert_eq!(
+            project("a {# ty: ignore #}\n{% iff book %}\n").diagnostics(),
+            ["unknown-template-tag Error: no template tag named `iff` [iff]"]
+        );
+    }
+
+    #[test]
+    fn a_project_whose_settings_cannot_be_read_reports_nothing_it_would_have_to_guess() {
+        // no `manage.py`, so no `INSTALLED_APPS` — and without those there is no
+        // saying what a tag library, a template or a static file even is
+        let test = TemplateTest::new(&[
+            ("blog/__init__.py", ""),
+            (
+                "blog/templates/blog/post.html",
+                "{% load nope %}{% extends 'blog/nope.html' %}{% iff x %}{{ x|nope }}\n",
+            ),
+        ]);
+
+        assert!(test.diagnostics().is_empty());
+    }
+
+    #[test]
+    fn a_project_whose_url_tree_cannot_be_walked_reports_no_route() {
+        // `ROOT_URLCONF` names a module nothing can reach, so every name it holds
+        // is a name that would be reported missing
+        let test = TemplateTest::new(&[
+            (
+                "manage.py",
+                "
+                import os
+
+                os.environ.setdefault('DJANGO_SETTINGS_MODULE', 'project.settings')
+                ",
+            ),
+            ("project/__init__.py", ""),
+            (
+                "project/settings.py",
+                "
+                INSTALLED_APPS = ['blog']
+
+                TEMPLATES = [{'APP_DIRS': True}]
+
+                ROOT_URLCONF = 'project.urls'
+                ",
+            ),
+            (
+                "project/urls.py",
+                "
+                from django.urls import include, path
+
+                urlpatterns = [path('blog/', include('nowhere.urls'))]
+                ",
+            ),
+            ("blog/__init__.py", ""),
+            ("blog/templates/blog/post.html", "{% url 'anything' %}\n"),
+        ]);
+
+        assert!(test.diagnostics().is_empty());
+    }
+}
diff --git a/crates/ty_ide/src/django_template/hover.rs b/crates/ty_ide/src/django_template/hover.rs
index b5e6ec3d0b..1029cb658a 100644
--- a/crates/ty_ide/src/django_template/hover.rs
+++ b/crates/ty_ide/src/django_template/hover.rs
@@ -334,8 +334,8 @@ impl Site<'_> {
 
         match resolve::resolve_root(self.db, self.file, self.index, self.offset, root) {
             Some(Origin::Binding(_)) => vec![Content::Text("bound by this template".to_string())],
-            Some(Origin::Context(_)) => {
-                vec![Content::Text("from the view's context".to_string())]
+            Some(Origin::Context(variable)) => {
+                vec![Content::Text(variable.source.description().to_string())]
             }
             None => Vec::new(),
         }
diff --git a/crates/ty_ide/src/django_template/index.rs b/crates/ty_ide/src/django_template/index.rs
index 9d072a2b61..25d10f938d 100644
--- a/crates/ty_ide/src/django_template/index.rs
+++ b/crates/ty_ide/src/django_template/index.rs
@@ -17,6 +17,9 @@ use ruff_text_size::{TextRange, TextSize};
 use super::builtins;
 use super::lexer::{Construct, ConstructKind, Lexed, Token, TokenKind, lex, string_contents};
 
+/// what django names a block tag's closing tag by
+pub(crate) const END_TAG_PREFIX: &str = "end";
+
 /// a name a template defines: a `{% block %}` or a `{% partialdef %}`
 #[derive(Debug, Clone, PartialEq, Eq, get_size2::GetSize)]
 pub(crate) struct Definition {
@@ -91,6 +94,18 @@ pub(crate) struct Block {
     pub(crate) closed: bool,
 }
 
+/// a closing tag that closed nothing
+///
+/// what makes a tag a closing one is that some other tag is waiting for it, so a
+/// tag nothing is waiting for is only a *candidate* — the reader decides whether
+/// the name is one django would have been waiting for.
+#[derive(Debug, Clone, PartialEq, Eq, get_size2::GetSize)]
+pub(crate) struct Stray {
+    pub(crate) name: CompactString,
+    /// the whole `{% end… %}` construct
+    pub(crate) range: TextRange,
+}
+
 /// a template, lexed and indexed
 ///
 /// every collection is boxed: the index is a salsa-cached value, and a `Vec`
@@ -100,12 +115,14 @@ pub(crate) struct Block {
 pub(crate) struct TemplateIndex {
     lexed: Lexed,
     extends: Option<TemplateReference>,
+    extends_unresolved: bool,
     includes: Box<[TemplateReference]>,
     blocks: Box<[Definition]>,
     partials: Box<[Definition]>,
     loads: Box<[Load]>,
     bindings: Box<[Binding]>,
     spans: Box<[Block]>,
+    strays: Box<[Stray]>,
 }
 
 impl TemplateIndex {
@@ -122,6 +139,16 @@ impl TemplateIndex {
         self.extends.as_ref()
     }
 
+    /// whether the template extends something no name can be read off
+    ///
+    /// `{% extends parent %}` picks its base at render time, so this template's
+    /// place in the inheritance tree is not knowable — which is a different
+    /// thing from extending nothing, and the difference matters to anything that
+    /// has to be sure it has found every template in a family.
+    pub(crate) fn extends_unresolved(&self) -> bool {
+        self.extends_unresolved
+    }
+
     /// every template this one includes
     pub(crate) fn includes(&self) -> &[TemplateReference] {
         &self.includes
@@ -168,6 +195,11 @@ impl TemplateIndex {
         &self.spans
     }
 
+    /// every `{% end… %}` that closed nothing, in source order
+    pub(crate) fn strays(&self) -> &[Stray] {
+        &self.strays
+    }
+
     /// the block tags still open at `offset`, innermost first
     ///
     /// this is what tells a completion inside `{% for %}…{% |` that the tag it
@@ -202,12 +234,14 @@ impl<'src> Builder<'src> {
         let end_tags = self.end_tags_present();
 
         let mut extends = None;
+        let mut extends_unresolved = false;
         let mut includes = Vec::new();
         let mut blocks = Vec::new();
         let mut partials = Vec::new();
         let mut loads = Vec::new();
         let mut bindings: Vec<Binding> = Vec::new();
         let mut spans = Vec::new();
+        let mut strays = Vec::new();
 
         let mut stack: Vec<Frame> = Vec::new();
         let template_end = TextSize::try_from(self.source.len()).unwrap_or_default();
@@ -238,11 +272,22 @@ impl<'src> Builder<'src> {
                 continue;
             }
 
+            if name.starts_with(END_TAG_PREFIX) {
+                strays.push(Stray {
+                    name: name.to_compact_string(),
+                    range: construct.range,
+                });
+            }
+
             match name {
-                "extends" if extends.is_none() => {
-                    extends = arguments
+                "extends" if extends.is_none() && !extends_unresolved => {
+                    match arguments
                         .iter()
-                        .find_map(|token| self.template_reference(token));
+                        .find_map(|token| self.template_reference(token))
+                    {
+                        Some(reference) => extends = Some(reference),
+                        None => extends_unresolved = true,
+                    }
                 }
                 "include" => {
                     if let Some(reference) = arguments
@@ -279,7 +324,7 @@ impl<'src> Builder<'src> {
                     // it is actually paired with in this file. this needs no
                     // knowledge of the tag's python definition, which is what
                     // makes unknown libraries behave.
-                    let candidate = format!("end{name}");
+                    let candidate = format!("{END_TAG_PREFIX}{name}");
                     end_tags
                         .contains(&candidate.as_str())
                         .then(|| candidate.to_compact_string())
@@ -312,12 +357,14 @@ impl<'src> Builder<'src> {
         TemplateIndex {
             lexed: self.lexed,
             extends,
+            extends_unresolved,
             includes: includes.into_boxed_slice(),
             blocks: blocks.into_boxed_slice(),
             partials: partials.into_boxed_slice(),
             loads: loads.into_boxed_slice(),
             bindings: bindings.into_boxed_slice(),
             spans: spans.into_boxed_slice(),
+            strays: strays.into_boxed_slice(),
         }
     }
 
@@ -329,7 +376,7 @@ impl<'src> Builder<'src> {
             .iter()
             .filter_map(|construct| construct.name)
             .map(|range| &self.source[range])
-            .filter(|name| name.starts_with("end"))
+            .filter(|name| name.starts_with(END_TAG_PREFIX))
             .collect();
         names.sort_unstable();
         names.dedup();
@@ -689,6 +736,15 @@ mod tests {
         );
     }
 
+    #[test]
+    fn an_extends_that_names_no_template_is_told_apart_from_no_extends_at_all() {
+        assert!(!index("{% block a %}{% endblock %}").extends_unresolved());
+
+        let dynamic = index("{% extends parent %}");
+        assert!(dynamic.extends().is_none());
+        assert!(dynamic.extends_unresolved());
+    }
+
     #[test]
     fn a_reference_can_address_a_partial_inside_a_template() {
         let index = index("{% include 'blog.html#comment-item' %}");
diff --git a/crates/ty_ide/src/django_template/project.rs b/crates/ty_ide/src/django_template/project.rs
index 60319aea0c..a89a34cefb 100644
--- a/crates/ty_ide/src/django_template/project.rs
+++ b/crates/ty_ide/src/django_template/project.rs
@@ -22,7 +22,7 @@ use ruff_db::system::walk_directory::WalkState;
 use ruff_db::system::{FileType, SystemPath, SystemPathBuf};
 use ruff_python_ast::visitor::{Visitor, walk_expr, walk_stmt};
 use ruff_python_ast::{self as ast, AnyNodeRef, Expr, Stmt};
-use ruff_text_size::{Ranged, TextRange};
+use ruff_text_size::{Ranged, TextRange, TextSize};
 use rustc_hash::{FxHashMap, FxHashSet};
 use ty_module_resolver::{Module, ModuleName, resolve_module, resolve_real_module};
 use ty_project::{Db, Project};
@@ -67,6 +67,37 @@ const OPTIONS_KEY: &str = "OPTIONS";
 /// the option naming the libraries every template has loaded already
 const BUILTINS_OPTION: &str = "builtins";
 
+/// the option an engine replaces the default template loaders with
+const LOADERS_OPTION: &str = "loaders";
+
+/// the option naming the functions every render merges the result of into its context
+const CONTEXT_PROCESSORS_OPTION: &str = "context_processors";
+
+/// the keyword a render call passes its context by
+const CONTEXT_KEYWORD: &str = "context";
+
+/// the class attribute a generic view names the object it renders by
+const CONTEXT_OBJECT_NAME_ATTRIBUTE: &str = "context_object_name";
+
+/// the class attribute a view adds fixed names to its context through
+const EXTRA_CONTEXT_ATTRIBUTE: &str = "extra_context";
+
+/// the method a class-based view builds its context in
+const GET_CONTEXT_DATA_METHOD: &str = "get_context_data";
+
+/// the method a context dict is extended in place with
+const CONTEXT_UPDATE_METHOD: &str = "update";
+
+/// how many names deep a context held in a variable is followed
+///
+/// each hop is a `{**base}` spread or a name bound to another, and a project
+/// nests a couple at most. bounding it is what keeps a context built out of
+/// itself from being followed for ever.
+const MAX_CONTEXT_DEPTH: usize = 4;
+
+/// how many base classes deep a view's context is collected from
+const MAX_VIEW_DEPTH: usize = 8;
+
 /// django's own package, whose `templatetags` is a library candidate like any
 /// installed app's
 const DJANGO_PACKAGE: &str = "django";
@@ -86,6 +117,16 @@ pub(crate) const TEMPLATE_NAME_ATTRIBUTE: &str = "template_name";
 /// the functions that resolve a route to its url by name
 pub(crate) const REVERSE_CALLEES: &[&str] = &["reverse", "reverse_lazy"];
 
+/// the keyword those functions take the route name by
+const REVERSE_NAME_KEYWORD: &str = "viewname";
+
+/// the keyword a rest framework hyperlinked field names its route by
+///
+/// a `HyperlinkedIdentityField(view_name="blog:detail")` reverses a route as
+/// surely as a `reverse()` does, and the keyword is distinctive enough to be
+/// read on sight wherever the field is built.
+const HYPERLINK_NAME_KEYWORD: &str = "view_name";
+
 /// the function that redirects to a route named the same way
 ///
 /// it is kept apart from [`REVERSE_CALLEES`] because it accepts a model or a url
@@ -114,7 +155,7 @@ const APP_NAME_VARIABLE: &str = "app_name";
 const URLPATTERNS_VARIABLE: &str = "urlpatterns";
 
 /// the separator django writes between a namespace and the name it qualifies
-const NAMESPACE_SEPARATOR: char = ':';
+pub(crate) const NAMESPACE_SEPARATOR: char = ':';
 
 /// the method a rest framework router routes a viewset with
 const ROUTER_REGISTER_METHOD: &str = "register";
@@ -227,8 +268,36 @@ pub(crate) struct UrlName {
     pub(crate) file: File,
     /// the `name=` literal, for navigation
     pub(crate) range: TextRange,
-    /// the route pattern, shown alongside the completion
+    /// the route pattern, every prefix it is mounted under included
+    ///
+    /// `None` where some part of the pattern could not be read, which is the
+    /// difference between a route that takes no arguments and one whose
+    /// arguments are unknown.
     pub(crate) route: Option<Box<str>>,
+    /// whether `route` is the whole pattern django reverses against
+    ///
+    /// a rest framework router generates its routes from a prefix rather than
+    /// writing them out, so what one of them takes cannot be read off `route`.
+    pub(crate) exact: bool,
+}
+
+/// where a name in a template's context comes from
+#[derive(Debug, Clone, Copy, PartialEq, Eq, get_size2::GetSize)]
+pub(crate) enum ContextSource {
+    /// a view put it in this template's context
+    View,
+    /// a context processor puts it in every template's context
+    Processor,
+}
+
+impl ContextSource {
+    /// how the name's provenance reads, for a name nothing gives a type to
+    pub(crate) fn description(self) -> &'static str {
+        match self {
+            Self::View => "from the view's context",
+            Self::Processor => "from a context processor",
+        }
+    }
 }
 
 /// a name a view puts in a template's context
@@ -243,6 +312,7 @@ pub(crate) struct ContextVariable {
     /// this is what the completions infer the variable's type from, which is how
     /// a django model in the context brings its fields with it.
     pub(crate) value: Option<TextRange>,
+    pub(crate) source: ContextSource,
 }
 
 /// the context one template is rendered with, from one place that renders it
@@ -266,6 +336,24 @@ pub(crate) struct DiscoveredFile {
     /// django loads. every consumer of a discovery takes the first file of a
     /// name, so this is what puts that one first.
     precedence: usize,
+    /// whether django loads it out of a directory of the project's own
+    ///
+    /// an installed app in site-packages holds templates django loads exactly as
+    /// it loads the project's, and they are equally real to everything that only
+    /// reads them — but they are not the project's to rewrite.
+    pub(crate) own: bool,
+}
+
+impl DiscoveredFile {
+    /// the directory the file's name is relative to
+    ///
+    /// this is the directory django's loader searched to find it, which is where
+    /// a file renamed to another name would have to end up.
+    pub(crate) fn root(&self) -> Option<&SystemPath> {
+        self.path
+            .ancestors()
+            .nth(self.name.matches('/').count() + 1)
+    }
 }
 
 /// every file under a `templates` directory of the project, or one its settings name
@@ -290,6 +378,29 @@ pub(crate) fn static_files(db: &dyn Db, project: Project) -> Box<[DiscoveredFile
     )
 }
 
+/// whether everything the settings say about the project was worked out
+///
+/// what the templates, the static files and the tag libraries are discovered
+/// from is a union of what the convention finds and what the settings name,
+/// which is the right answer for a *suggestion*: a directory too many costs a
+/// completion nobody wanted. a diagnostic needs the opposite guarantee, that
+/// nothing is missing, and only a settings module read all the way through gives
+/// it — without one there is no `INSTALLED_APPS`, and without that an installed
+/// app's own templates and libraries are somewhere nothing here will ever look.
+#[salsa::tracked(returns(copy))]
+pub(crate) fn settings_are_authoritative(db: &dyn Db, project: Project) -> bool {
+    let Some(importing) = *settings_file(db, project) else {
+        return false;
+    };
+    let settings = django_settings(db, project);
+
+    settings.read_in_full
+        && settings
+            .installed_apps
+            .iter()
+            .all(|app| app_package(db, importing, app).is_some())
+}
+
 /// the file a template name resolves to
 pub(crate) fn resolve_template(db: &dyn Db, name: &str) -> Option<File> {
     let path = template_files(db, db.project())
@@ -495,22 +606,41 @@ fn is_stub(db: &dyn Db, file: File) -> bool {
 /// costs a suggestion where having fewer would cost a wrong diagnostic.
 #[salsa::tracked(returns(ref), heap_size=ruff_memory_usage::heap_size)]
 pub(crate) fn url_names(db: &dyn Db, project: Project) -> Box<[UrlName]> {
-    let Some(root) = *root_urlconf(db, project) else {
-        return project_scan(db, project, flat_url_names);
-    };
+    walk_urls(db, project).map_or_else(
+        || project_scan(db, project, flat_url_names),
+        |walk| walk.found.into_boxed_slice(),
+    )
+}
+
+/// whether the route names are the ones django would reverse, and all of them
+///
+/// only a walk from `ROOT_URLCONF` puts a name under the namespace django gives
+/// it, and only a walk that got all the way through every include it met has
+/// seen every name there is. anything short of that is a set of names a "no such
+/// route" would be wrong about, so it answers nothing rather than something
+/// plausible.
+#[salsa::tracked(returns(copy))]
+pub(crate) fn routes_are_authoritative(db: &dyn Db, project: Project) -> bool {
+    walk_urls(db, project).is_some_and(|walk| walk.complete)
+}
+
+/// the url tree walked from `ROOT_URLCONF`, for a project that names one
+fn walk_urls(db: &dyn Db, project: Project) -> Option<UrlWalk<'_>> {
+    let root = (*root_urlconf(db, project))?;
 
     let mut walk = UrlWalk {
         db,
         found: Vec::new(),
         visited: FxHashSet::default(),
+        complete: true,
     };
-    walk.mount(root, URLPATTERNS_VARIABLE, "", MAX_URLCONF_DEPTH);
+    walk.mount(root, URLPATTERNS_VARIABLE, "", Some(""), MAX_URLCONF_DEPTH);
 
-    let mut found = walk.found;
     let mut seen = FxHashSet::default();
-    found.retain(|url| seen.insert((url.name.clone(), url.file, url.range)));
+    walk.found
+        .retain(|url| seen.insert((url.name.clone(), url.file, url.range)));
 
-    found.into_boxed_slice()
+    Some(walk)
 }
 
 /// the module the project's url tree starts at
@@ -533,7 +663,7 @@ fn flat_url_names(db: &dyn Db, file: File) -> impl Iterator<Item = UrlName> {
     conf.entries
         .iter()
         .filter_map(move |entry| match &entry.kind {
-            UrlEntryKind::Route(route) => Some(namespaced(route, &namespace)),
+            UrlEntryKind::Route(route) => Some(mounted(route, &namespace, Some(""))),
             // an include is a tree the flat scan has no way to walk: the module it
             // names contributes its own names when the scan reaches it
             UrlEntryKind::Include(_) => None,
@@ -550,70 +680,118 @@ struct UrlWalk<'db> {
     /// of one module under two namespaces are two different sets of names — so
     /// it is the whole triple that decides whether there is anything left to do.
     visited: FxHashSet<(File, CompactString, CompactString)>,
+    /// whether every module the walk met was read all the way through
+    complete: bool,
 }
 
 impl UrlWalk<'_> {
-    /// walk the routes `binding` of `file` holds, namespaced under `prefix`
-    fn mount(&mut self, file: File, binding: &str, prefix: &str, depth: usize) {
-        if depth == 0
-            || !self.visited.insert((
-                file,
-                binding.to_compact_string(),
-                prefix.to_compact_string(),
-            ))
-        {
+    /// walk the routes `binding` of `file` holds, mounted under `namespace` and
+    /// behind the route pattern `prefix`
+    fn mount(
+        &mut self,
+        file: File,
+        binding: &str,
+        namespace: &str,
+        prefix: Option<&str>,
+        depth: usize,
+    ) {
+        if depth == 0 {
+            // a tree deeper than the walk goes is one whose names are not all here
+            self.complete = false;
+            return;
+        }
+        if !self.visited.insert((
+            file,
+            binding.to_compact_string(),
+            namespace.to_compact_string(),
+        )) {
             return;
         }
 
         let db = self.db;
+        let conf = urlconf(db, file);
+        self.complete &= conf.complete;
+
         // including a module mounts its `urlpatterns`, and a route the module
         // writes outside any list at all is taken along rather than lost
         let whole_module = binding == URLPATTERNS_VARIABLE;
+        let mut mounted_anything = false;
 
-        for entry in &urlconf(db, file).entries {
-            let mounted = match &entry.binding {
+        for entry in &conf.entries {
+            let is_mounted = match &entry.binding {
                 Some(bound) => bound == binding,
                 None => whole_module,
             };
-            if !mounted {
+            if !is_mounted {
                 continue;
             }
+            mounted_anything = true;
 
             match &entry.kind {
-                UrlEntryKind::Route(route) => self.found.push(namespaced(route, prefix)),
-                UrlEntryKind::Include(include) => self.follow(file, include, prefix, depth),
+                UrlEntryKind::Route(route) => self.found.push(mounted(route, namespace, prefix)),
+                UrlEntryKind::Include(include) => {
+                    self.follow(file, include, namespace, prefix, depth);
+                }
             }
         }
+
+        // a list this module never binds is one built somewhere the scan cannot
+        // read — by a helper, or by a router registering through a name of its
+        // own — so what it mounts is not in the answer
+        self.complete &= whole_module || mounted_anything;
     }
 
     /// walk what an include mounts, under the namespace it mounts it in
-    fn follow(&mut self, file: File, include: &Include, prefix: &str, depth: usize) {
+    fn follow(
+        &mut self,
+        file: File,
+        include: &Include,
+        namespace: &str,
+        prefix: Option<&str>,
+        depth: usize,
+    ) {
+        let prefix = join_routes(prefix, include.prefix.as_deref());
+
         match &include.target {
             IncludeTarget::Local(binding) => {
-                let prefix = extend(prefix, include.namespace.as_deref());
-                self.mount(file, binding, &prefix, depth - 1);
+                let namespace = extend(namespace, include.namespace.as_deref());
+                self.mount(file, binding, &namespace, prefix.as_deref(), depth - 1);
             }
             IncludeTarget::Module(module) => {
                 let Some(included) = ModuleName::new(module)
                     .and_then(|module| resolve_real_module(self.db, file, &module))
                     .and_then(|module| module.file(self.db))
                 else {
+                    // a urlconf that can't be reached holds names the walk will
+                    // never see
+                    self.complete = false;
                     return;
                 };
                 // an include that names no namespace leaves the included module
                 // to name its own
-                let namespace = include
+                let instance = include
                     .namespace
                     .clone()
                     .or_else(|| urlconf(self.db, included).app_name.clone());
-                let prefix = extend(prefix, namespace.as_deref());
-
-                self.mount(included, URLPATTERNS_VARIABLE, &prefix, depth - 1);
+                let namespace = extend(namespace, instance.as_deref());
+
+                self.mount(
+                    included,
+                    URLPATTERNS_VARIABLE,
+                    &namespace,
+                    prefix.as_deref(),
+                    depth - 1,
+                );
             }
         }
     }
 }
 
+/// one route pattern written after another, when both are known
+fn join_routes(prefix: Option<&str>, own: Option<&str>) -> Option<CompactString> {
+    Some(format!("{}{}", prefix?, own?).to_compact_string())
+}
+
 /// `prefix` with `namespace` qualified under it, as django writes it
 fn extend(prefix: &str, namespace: Option<&str>) -> CompactString {
     match namespace {
@@ -623,10 +801,11 @@ fn extend(prefix: &str, namespace: Option<&str>) -> CompactString {
     }
 }
 
-/// `route` as it is reversed from under `prefix`
-fn namespaced(route: &UrlName, prefix: &str) -> UrlName {
+/// `route` as it is reversed from under `namespace`, behind the pattern `prefix`
+fn mounted(route: &UrlName, namespace: &str, prefix: Option<&str>) -> UrlName {
     UrlName {
-        name: extend(prefix, Some(&route.name)),
+        name: extend(namespace, Some(&route.name)),
+        route: join_routes(prefix, route.route.as_deref()).map(|route| route.as_str().into()),
         ..route.clone()
     }
 }
@@ -663,6 +842,274 @@ pub(crate) fn context_for_template<'db>(
     seen
 }
 
+/// where a python module writes a template or a route name
+///
+/// [`super::python`] reads one of these at a cursor, which is all a completion or
+/// a goto ever needs. a rename needs the opposite: every place in the project the
+/// name is written, since one left behind is a project silently broken. so an
+/// expression in one of those positions is recorded whether or not it is a
+/// literal — a `render(request, chosen)` names a template nothing here can read,
+/// and what a rename cannot read it must refuse rather than work around.
+#[derive(Debug, Clone, PartialEq, Eq, get_size2::GetSize)]
+pub(crate) struct NameUse {
+    /// the literal's value, or `None` where the expression is no literal at all
+    pub(crate) name: Option<CompactString>,
+    /// whether the name is written as one literal a single range could replace
+    ///
+    /// `"blog/" "post.html"` reads as one name to python and as nothing a range
+    /// could cover to a rename.
+    pub(crate) whole: bool,
+    pub(crate) file: File,
+    /// the literal's contents, its quotes excluded — or the whole expression,
+    /// where there is nothing to replace, so that a refusal can point at it
+    pub(crate) range: TextRange,
+}
+
+impl NameUse {
+    /// what `expr` writes, read as a name
+    fn of(file: File, expr: &Expr) -> Self {
+        let Expr::StringLiteral(literal) = expr else {
+            return Self {
+                name: None,
+                whole: false,
+                file,
+                range: expr.range(),
+            };
+        };
+
+        let (whole, range) = match literal.value.as_slice() {
+            [part] => (true, part.content_range()),
+            _ => (false, literal.range()),
+        };
+
+        Self {
+            name: Some(literal.value.to_str().to_compact_string()),
+            whole,
+            file,
+            range,
+        }
+    }
+}
+
+/// every place the project's python names a template
+#[salsa::tracked(returns(ref), heap_size=ruff_memory_usage::heap_size)]
+pub(crate) fn template_uses(db: &dyn Db, project: Project) -> Box<[NameUse]> {
+    project_scan(db, project, |db, file| {
+        template_uses_in_file(db, file).iter().cloned()
+    })
+}
+
+/// every place the project's python reverses a route by name
+#[salsa::tracked(returns(ref), heap_size=ruff_memory_usage::heap_size)]
+pub(crate) fn route_uses(db: &dyn Db, project: Project) -> Box<[NameUse]> {
+    project_scan(db, project, |db, file| {
+        route_uses_in_file(db, file).iter().cloned()
+    })
+}
+
+/// the templates one module names
+#[salsa::tracked(returns(ref), heap_size=ruff_memory_usage::heap_size)]
+fn template_uses_in_file(db: &dyn Db, file: File) -> Box<[NameUse]> {
+    if !mentions(db, file, CONTEXT_CALLEES) && !mentions(db, file, &[TEMPLATE_NAME_ATTRIBUTE]) {
+        return Box::default();
+    }
+
+    let parsed = parsed_module(db, file).load(db);
+    let mut visitor = TemplateUseVisitor {
+        file,
+        found: Vec::new(),
+    };
+    visitor.visit_body(parsed.suite());
+
+    visitor.found.into_boxed_slice()
+}
+
+struct TemplateUseVisitor {
+    file: File,
+    found: Vec<NameUse>,
+}
+
+impl<'ast> Visitor<'ast> for TemplateUseVisitor {
+    fn visit_stmt(&mut self, stmt: &'ast Stmt) {
+        // `template_name = "…"` names a template where django reads one, which is
+        // the body of a view class
+        if let Stmt::ClassDef(class) = stmt {
+            self.found.extend(
+                class
+                    .body
+                    .iter()
+                    .filter_map(|statement| class_attribute(statement, TEMPLATE_NAME_ATTRIBUTE))
+                    .map(|(value, _)| NameUse::of(self.file, value)),
+            );
+        }
+
+        walk_stmt(self, stmt);
+    }
+
+    fn visit_expr(&mut self, expr: &'ast Expr) {
+        if let Expr::Call(call) = expr
+            && callee_name(&call.func)
+                .is_some_and(|callee| CONTEXT_CALLEES.contains(&callee.as_str()))
+            && let Some(template) = call
+                .arguments
+                .find_argument_value(TEMPLATE_NAME_ATTRIBUTE, 1)
+        {
+            self.found.push(NameUse::of(self.file, template));
+        }
+
+        walk_expr(self, expr);
+    }
+}
+
+/// the routes one module reverses
+#[salsa::tracked(returns(ref), heap_size=ruff_memory_usage::heap_size)]
+fn route_uses_in_file(db: &dyn Db, file: File) -> Box<[NameUse]> {
+    if !mentions(db, file, REVERSE_CALLEES)
+        && !mentions(db, file, &[REDIRECT_CALLEE, HYPERLINK_NAME_KEYWORD])
+    {
+        return Box::default();
+    }
+
+    let parsed = parsed_module(db, file).load(db);
+    let mut visitor = RouteUseVisitor {
+        file,
+        found: Vec::new(),
+    };
+    visitor.visit_body(parsed.suite());
+
+    visitor.found.into_boxed_slice()
+}
+
+struct RouteUseVisitor {
+    file: File,
+    found: Vec<NameUse>,
+}
+
+impl<'ast> Visitor<'ast> for RouteUseVisitor {
+    fn visit_expr(&mut self, expr: &'ast Expr) {
+        if let Expr::Call(call) = expr
+            && let Some(callee) = callee_name(&call.func)
+        {
+            if REVERSE_CALLEES.contains(&callee.as_str())
+                && let Some(argument) = call.arguments.find_argument_value(REVERSE_NAME_KEYWORD, 0)
+            {
+                self.found.push(NameUse::of(self.file, argument));
+            } else if callee == REDIRECT_CALLEE
+                && let Some(argument) = call.arguments.args.first()
+                && let use_ = NameUse::of(self.file, argument)
+                // a redirect takes a url or a model as readily as a route name,
+                // so only a literal that could be a name is read as one — a
+                // `redirect(book)` is not a route this has failed to read
+                && use_
+                    .name
+                    .as_ref()
+                    .is_some_and(|name| !name.contains('/'))
+            {
+                self.found.push(use_);
+            }
+        }
+
+        // a rest framework hyperlinked field names the route it points at by
+        // keyword, wherever it is built
+        if let Expr::Call(call) = expr
+            && let Some(keyword) = call.arguments.find_keyword(HYPERLINK_NAME_KEYWORD)
+        {
+            self.found.push(NameUse::of(self.file, &keyword.value));
+        }
+
+        walk_expr(self, expr);
+    }
+}
+
+/// a constant the project binds one of the names being renamed to
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub(crate) struct BoundName {
+    pub(crate) file: File,
+    /// the literal, so that a caller can tell a binding it is already rewriting
+    /// from one it is not
+    pub(crate) value: TextRange,
+    /// the name the literal is bound to, which is what a refusal points at
+    pub(crate) bound_to: CompactString,
+    /// where that name is written
+    pub(crate) range: TextRange,
+}
+
+/// every module- or class-level name the project binds one of `names` to
+///
+/// a rename rewrites the positions it recognises, and a name written straight
+/// into one of them is one it can follow. a constant is the way a name reaches
+/// such a position without being written there — `TEMPLATE = "blog/base.html"`
+/// and then a `render(request, TEMPLATE)`, or a helper somewhere this cannot
+/// see at all — and following that is beyond anything here, so it refuses.
+///
+/// the search is deliberately not "every literal that spells the name": a
+/// `detail` or a `content` is among the commonest strings in any codebase, and
+/// an `item.get("detail")` in unrelated code is no reason to refuse anything. a
+/// binding is the narrowest thing that could still carry the name somewhere.
+pub(crate) fn bound_names(db: &dyn Db, names: &[&str]) -> Vec<BoundName> {
+    let mut found = Vec::new();
+
+    for file in &db.project().files(db) {
+        if is_stub(db, file) || !mentions(db, file, names) {
+            continue;
+        }
+
+        let parsed = parsed_module(db, file).load(db);
+        bindings_in(file, parsed.suite(), names, &mut found);
+    }
+
+    found
+}
+
+/// the bindings of `body`, and of the classes it declares
+///
+/// a function body is left out: a name bound there is visible only inside it, so
+/// it can only reach a template or a route through a call this already reads —
+/// and reads as an argument it cannot follow, which refuses on its own.
+fn bindings_in(file: File, body: &[Stmt], names: &[&str], found: &mut Vec<BoundName>) {
+    for statement in body {
+        if let Stmt::ClassDef(class) = statement {
+            bindings_in(file, &class.body, names, found);
+            continue;
+        }
+
+        let Some((bound_to, range, value)) = binding(statement) else {
+            continue;
+        };
+        let Expr::StringLiteral(literal) = value else {
+            continue;
+        };
+        if !names.contains(&literal.value.to_str()) {
+            continue;
+        }
+
+        found.push(BoundName {
+            file,
+            value: match literal.value.as_slice() {
+                [part] => part.content_range(),
+                _ => literal.range(),
+            },
+            bound_to: bound_to.to_compact_string(),
+            range,
+        });
+    }
+}
+
+/// the name a statement binds, where it writes it, and what it binds to it
+fn binding(statement: &Stmt) -> Option<(&str, TextRange, &Expr)> {
+    match statement {
+        Stmt::Assign(assign) => match assign.targets.as_slice() {
+            [Expr::Name(target)] => Some((target.id.as_str(), target.range(), &*assign.value)),
+            _ => None,
+        },
+        Stmt::AnnAssign(assign) => match (&*assign.target, assign.value.as_deref()) {
+            (Expr::Name(target), Some(value)) => Some((target.id.as_str(), target.range(), value)),
+            _ => None,
+        },
+        _ => None,
+    }
+}
+
 /// run `scan` over every first-party source file of the project
 fn project_scan<'db, T, I>(
     db: &'db dyn Db,
@@ -708,7 +1155,22 @@ fn discover(
     // a directory the settings name is under no obligation to be called
     // `templates`, nor to sit under the project root, so it gets a walk of its own
     for (precedence, root) in order.named.iter().enumerate() {
-        collect_under(db, project, root, precedence, &mut found);
+        collect_under(db, project, root, precedence, true, &mut found);
+    }
+
+    // an installed app is as often as not a package in site-packages, whose
+    // `templates` directory the convention walk of the project root never
+    // reaches. django loads `admin/base_site.html` and `rest_framework/api.html`
+    // from exactly there
+    for (index, app) in order.apps.iter().enumerate() {
+        collect_under(
+            db,
+            project,
+            &app.join(directory),
+            order.named.len() + index,
+            false,
+            &mut found,
+        );
     }
 
     found.sort_by(|left, right| {
@@ -717,7 +1179,15 @@ fn discover(
             .then(left.precedence.cmp(&right.precedence))
             .then(left.path.cmp(&right.path))
     });
-    found.dedup_by(|left, right| left.name == right.name && left.path == right.path);
+    // one file reached two ways is one file, and the project's own if either way
+    // was the project's
+    found.dedup_by(|left, right| {
+        let same = left.name == right.name && left.path == right.path;
+        if same {
+            right.own |= left.own;
+        }
+        same
+    });
     found.into_boxed_slice()
 }
 
@@ -767,6 +1237,10 @@ fn discover_by_convention(
                                 name,
                                 path: entry.path().to_path_buf(),
                                 precedence: order.rank(under),
+                                // the walk starts at the project root and
+                                // respects its ignore rules, so whatever it
+                                // reaches is the project's own
+                                own: true,
                             });
                         }
                         WalkState::Continue
@@ -787,6 +1261,7 @@ fn collect_under(
     project: Project,
     root: &SystemPath,
     precedence: usize,
+    own: bool,
     found: &mut Vec<DiscoveredFile>,
 ) {
     let collected = Mutex::new(Vec::new());
@@ -808,6 +1283,7 @@ fn collect_under(
                         name,
                         path: entry.path().to_path_buf(),
                         precedence,
+                        own,
                     });
                 }
 
@@ -1112,7 +1588,7 @@ fn app_directories(db: &dyn Db, project: Project, apps: &[CompactString]) -> Box
 }
 
 /// what the project's django settings module says about where its files live
-#[derive(Debug, Default, Clone, PartialEq, Eq, get_size2::GetSize)]
+#[derive(Debug, Clone, PartialEq, Eq, get_size2::GetSize)]
 struct DjangoSettings {
     /// the directories `TEMPLATES[*]["DIRS"]` names
     template_dirs: Box<[SystemPathBuf]>,
@@ -1127,6 +1603,31 @@ struct DjangoSettings {
     /// the modules `TEMPLATES[*]["OPTIONS"]["builtins"]` names, whose tags and
     /// filters every template has without saying `{% load %}`
     always_loaded: Box<[CompactString]>,
+    /// the functions `TEMPLATES[*]["OPTIONS"]["context_processors"]` names, whose
+    /// returned names every template is rendered with
+    context_processors: Box<[CompactString]>,
+    /// whether every directory and module the settings name was worked out
+    ///
+    /// a `DIRS` entry built from an environment variable, or an engine that
+    /// configures its own `loaders`, leaves django loading from somewhere this
+    /// has no way to look — which is a template set nothing may call complete.
+    read_in_full: bool,
+}
+
+impl Default for DjangoSettings {
+    fn default() -> Self {
+        Self {
+            template_dirs: Box::default(),
+            app_directories: false,
+            static_dirs: Box::default(),
+            installed_apps: Box::default(),
+            root_urlconf: None,
+            always_loaded: Box::default(),
+            context_processors: Box::default(),
+            // the settings that were read, all none of them, were read in full
+            read_in_full: true,
+        }
+    }
 }
 
 /// what the project's settings module says
@@ -1274,8 +1775,11 @@ impl SettingsReader {
                 TEMPLATES_SETTING => self.engines(&assign.value, &mut template_dirs),
                 STATICFILES_DIRS_SETTING => static_dirs.extend(self.directories(&assign.value)),
                 INSTALLED_APPS_SETTING => {
-                    installed_apps
-                        .extend(elements(&assign.value).iter().filter_map(string_literal));
+                    let named = elements(&assign.value);
+                    installed_apps.extend(named.iter().filter_map(string_literal));
+                    // an app whose entry isn't written out is an app whose
+                    // templates and libraries are not in the answer
+                    self.settings.read_in_full &= installed_apps.len() == named.len();
                 }
                 ROOT_URLCONF_SETTING => {
                     self.settings.root_urlconf = string_literal(&assign.value);
@@ -1323,30 +1827,54 @@ impl SettingsReader {
 
     /// read the engine options that matter here
     ///
-    /// `builtins` is the one: a module it names is loaded into every template the
+    /// `builtins` is one: a module it names is loaded into every template the
     /// engine renders, so nothing in a template has to `{% load %}` it.
+    /// `context_processors` is the other, and names the functions whose result
+    /// every template is rendered with.
     fn options(&mut self, expr: &Expr) {
         let Expr::Dict(options) = expr else {
             return;
         };
 
         let mut always_loaded: Vec<CompactString> = self.settings.always_loaded.to_vec();
+        let mut context_processors: Vec<CompactString> = self.settings.context_processors.to_vec();
 
         for item in &options.items {
-            if item.key.as_ref().and_then(string_literal).as_deref() == Some(BUILTINS_OPTION) {
-                always_loaded.extend(elements(&item.value).iter().filter_map(string_literal));
+            match item.key.as_ref().and_then(string_literal).as_deref() {
+                Some(BUILTINS_OPTION) => {
+                    let named = elements(&item.value);
+                    always_loaded.extend(named.iter().filter_map(string_literal));
+                    self.settings.read_in_full &= always_loaded.len() == named.len();
+                }
+                // a processor that can't be read costs a name nothing reports
+                // against, so it leaves the settings authoritative as they were
+                Some(CONTEXT_PROCESSORS_OPTION) => {
+                    context_processors
+                        .extend(elements(&item.value).iter().filter_map(string_literal));
+                }
+                // an engine listing its own loaders loads from wherever they say,
+                // which need not be a directory at all
+                Some(LOADERS_OPTION) => self.settings.read_in_full = false,
+                _ => {}
             }
         }
 
         self.settings.always_loaded = always_loaded.into_boxed_slice();
+        self.settings.context_processors = context_processors.into_boxed_slice();
     }
 
     /// the directories a list of them names, the ones that can't be worked out dropped
-    fn directories(&self, expr: &Expr) -> Vec<SystemPathBuf> {
-        elements(expr)
+    fn directories(&mut self, expr: &Expr) -> Vec<SystemPathBuf> {
+        let named = elements(expr);
+        let found: Vec<SystemPathBuf> = named
             .iter()
             .filter_map(|element| self.paths.path(element))
-            .collect()
+            .collect();
+
+        // a directory django loads from and this cannot name is one whose
+        // templates are missing from every answer below
+        self.settings.read_in_full &= found.len() == named.len();
+        found
     }
 }
 
@@ -1431,11 +1959,28 @@ impl PathEvaluator {
 /// the entries are read without a namespace applied: which namespace a name ends
 /// up under is for the include that reaches it to say, and one module reached
 /// two ways is namespaced two ways.
-#[derive(Debug, Default, Clone, PartialEq, Eq, get_size2::GetSize)]
+#[derive(Debug, Clone, PartialEq, Eq, get_size2::GetSize)]
 struct UrlConf {
     /// the namespace an include of this module falls back to
     app_name: Option<CompactString>,
     entries: Box<[UrlEntry]>,
+    /// whether every route the module names was read
+    ///
+    /// a route whose name or whose mounted list could not be worked out leaves a
+    /// name behind that nothing here will ever report, which is exactly the
+    /// state in which a "no such route" would be wrong.
+    complete: bool,
+}
+
+impl Default for UrlConf {
+    fn default() -> Self {
+        Self {
+            app_name: None,
+            entries: Box::default(),
+            // a module that names no route at all is one there was nothing to miss in
+            complete: true,
+        }
+    }
 }
 
 /// one thing a url configuration module does
@@ -1463,6 +2008,8 @@ struct Include {
     target: IncludeTarget,
     /// the `namespace=`, or the instance namespace the two-tuple form names
     namespace: Option<CompactString>,
+    /// the route pattern the include is mounted behind, within this module
+    prefix: Option<CompactString>,
 }
 
 /// what an include mounts
@@ -1507,13 +2054,16 @@ fn urlconf(db: &dyn Db, file: File) -> UrlConf {
         db,
         file,
         binding: None,
+        prefix: Some(CompactString::default()),
         found: Vec::new(),
+        complete: true,
     };
     visitor.visit_body(parsed.suite());
 
     UrlConf {
         app_name,
         entries: visitor.found.into_boxed_slice(),
+        complete: visitor.complete,
     }
 }
 
@@ -1522,7 +2072,12 @@ struct UrlVisitor<'db> {
     file: File,
     /// the module-level name the statement being visited binds
     binding: Option<CompactString>,
+    /// the route pattern the call being visited is written inside, or `None`
+    /// where one of the patterns enclosing it could not be read
+    prefix: Option<CompactString>,
     found: Vec<UrlEntry>,
+    /// whether every route this module names was read
+    complete: bool,
 }
 
 impl UrlVisitor<'_> {
@@ -1533,7 +2088,8 @@ impl UrlVisitor<'_> {
         name: &str,
         file: File,
         range: TextRange,
-        route: Option<&str>,
+        route: Option<CompactString>,
+        exact: bool,
     ) {
         self.found.push(UrlEntry {
             binding,
@@ -1541,7 +2097,8 @@ impl UrlVisitor<'_> {
                 name: name.to_compact_string(),
                 file,
                 range,
-                route: route.map(Box::from),
+                route: route.map(|route| route.as_str().into()),
+                exact,
             }),
         });
     }
@@ -1550,7 +2107,11 @@ impl UrlVisitor<'_> {
     fn mounts(&mut self, target: IncludeTarget, namespace: Option<CompactString>) {
         self.found.push(UrlEntry {
             binding: self.binding.clone(),
-            kind: UrlEntryKind::Include(Include { target, namespace }),
+            kind: UrlEntryKind::Include(Include {
+                target,
+                namespace,
+                prefix: self.prefix.clone(),
+            }),
         });
     }
 
@@ -1571,11 +2132,16 @@ impl UrlVisitor<'_> {
         let (target, instance) = match argument {
             Expr::Tuple(pair) => match pair.elts.as_slice() {
                 [target, instance] => (target, string_literal(instance)),
-                _ => return,
+                _ => {
+                    self.complete = false;
+                    return;
+                }
             },
             _ => (argument, None),
         };
         let Some(target) = include_target(target) else {
+            // whatever this mounts, its names are not in the answer
+            self.complete = false;
             return;
         };
 
@@ -1611,28 +2177,33 @@ impl UrlVisitor<'_> {
             self.file,
             call.func.range(),
             None,
+            false,
         );
     }
 
     /// the name a `path()`-like call gives its route
     fn path_call(&mut self, call: &ast::ExprCall) {
-        if !callee_name(&call.func).is_some_and(|callee| URL_CALLEES.contains(&callee.as_str())) {
+        if !is_url_call(call) {
             return;
         }
         let Some(keyword) = call.arguments.find_keyword(URL_NAME_KEYWORD) else {
             return;
         };
         let Some(name) = string_literal(&keyword.value) else {
+            // a route django names and this doesn't is one a "no such route"
+            // would be wrong about
+            self.complete = false;
             return;
         };
 
-        let route = call.arguments.args.first().and_then(string_literal);
+        let route = join_routes(self.prefix.as_deref(), route_of(call).as_deref());
         self.record(
             self.binding.clone(),
             &name,
             self.file,
             keyword.value.range(),
-            route.as_deref(),
+            route,
+            true,
         );
     }
 
@@ -1655,12 +2226,14 @@ impl UrlVisitor<'_> {
             return;
         };
         let Some(prefix) = string_literal(prefix) else {
+            self.complete = false;
             return;
         };
         // the viewset is named either directly or through the module it lives in
         let Some(viewset @ (Expr::Name(_) | Expr::Attribute(_))) =
             call.arguments.find_argument_value("viewset", 1)
         else {
+            self.complete = false;
             return;
         };
 
@@ -1692,17 +2265,25 @@ impl UrlVisitor<'_> {
                 .and_then(|described| described.basename.clone())
             {
                 Some(basename) => (basename, viewset.range()),
-                None => return,
+                None => {
+                    self.complete = false;
+                    return;
+                }
             },
         };
 
+        // a router writes its own patterns from the prefix rather than taking
+        // them, so the prefix is what a route reads as but not what it takes
+        let route = join_routes(self.prefix.as_deref(), Some(prefix.as_str()));
+
         for suffix in ROUTER_ROUTE_SUFFIXES {
             self.record(
                 binding.clone(),
                 &format!("{basename}-{suffix}"),
                 self.file,
                 anchor,
-                Some(prefix.as_str()),
+                route.clone(),
+                false,
             );
         }
 
@@ -1713,7 +2294,8 @@ impl UrlVisitor<'_> {
                 &format!("{basename}-{}", action.url_name),
                 action.file,
                 action.range,
-                Some(prefix.as_str()),
+                route.clone(),
+                false,
             );
         }
     }
@@ -1738,7 +2320,7 @@ fn resolved_class<T>(
     db: &dyn Db,
     file: File,
     expr: &Expr,
-    read: impl Fn(File, &ast::StmtClassDef) -> T,
+    mut read: impl FnMut(File, &ast::StmtClassDef) -> T,
 ) -> Option<T> {
     let model = SemanticModel::new(db, file);
 
@@ -1990,16 +2572,40 @@ impl<'ast> Visitor<'ast> for UrlVisitor<'_> {
     }
 
     fn visit_expr(&mut self, expr: &'ast Expr) {
-        if let Expr::Call(call) = expr {
-            self.path_call(call);
-            self.router_registration(call);
-            self.include_call(call);
-        }
+        let Expr::Call(call) = expr else {
+            walk_expr(self, expr);
+            return;
+        };
+
+        self.path_call(call);
+        self.router_registration(call);
+        self.include_call(call);
+
+        // whatever this call holds — an `include()`, or a list of further routes —
+        // django mounts behind this call's own pattern
+        let outer = is_url_call(call).then(|| {
+            let inner = join_routes(self.prefix.as_deref(), route_of(call).as_deref());
+            std::mem::replace(&mut self.prefix, inner)
+        });
 
         walk_expr(self, expr);
+
+        if let Some(outer) = outer {
+            self.prefix = outer;
+        }
     }
 }
 
+/// whether `call` is a `path()`, `re_path()` or `url()`
+fn is_url_call(call: &ast::ExprCall) -> bool {
+    callee_name(&call.func).is_some_and(|callee| URL_CALLEES.contains(&callee.as_str()))
+}
+
+/// the pattern a `path()`-like call matches, when it is written out
+fn route_of(call: &ast::ExprCall) -> Option<CompactString> {
+    string_literal(call.arguments.args.first()?)
+}
+
 /// the template contexts one module builds
 #[salsa::tracked(returns(ref), heap_size=ruff_memory_usage::heap_size)]
 fn template_contexts_in_file(db: &dyn Db, file: File) -> Box<[TemplateContext]> {
@@ -2011,25 +2617,33 @@ fn template_contexts_in_file(db: &dyn Db, file: File) -> Box<[TemplateContext]>
     let parsed = parsed_module(db, file).load(db);
 
     let mut visitor = ContextVisitor {
+        db,
         file,
         found: Vec::new(),
+        scopes: Vec::new(),
     };
     visitor.visit_body(parsed.suite());
 
     visitor.found.into_boxed_slice()
 }
 
-struct ContextVisitor {
+struct ContextVisitor<'db, 'ast> {
+    db: &'db dyn Db,
     file: File,
     found: Vec<TemplateContext>,
+    /// the function bodies being walked, innermost last
+    ///
+    /// a context handed to `render()` by name is built by the statements of the
+    /// function that binds it, so that body is what the name is followed in.
+    scopes: Vec<&'ast [Stmt]>,
 }
 
-impl ContextVisitor {
+impl<'ast> ContextVisitor<'_, 'ast> {
     /// the context a `render()`/`TemplateResponse()` call passes
     ///
     /// both take the request first, the template second and the context third,
     /// and both accept those last two by keyword as well.
-    fn render_call(&self, call: &ast::ExprCall) -> Option<TemplateContext> {
+    fn render_call(&self, call: &'ast ast::ExprCall) -> Option<TemplateContext> {
         let callee = callee_name(&call.func)?;
         if !CONTEXT_CALLEES.contains(&callee.as_str()) {
             return None;
@@ -2046,38 +2660,26 @@ impl ContextVisitor {
 
         let context = call
             .arguments
-            .find_keyword("context")
+            .find_keyword(CONTEXT_KEYWORD)
             .map(|keyword| &keyword.value)
             .or_else(|| call.arguments.args.get(context_index));
 
         Some(TemplateContext {
             template,
             variables: context
-                .map(|context| self.dict_variables(context))
-                .unwrap_or_default(),
+                .map(|context| {
+                    context_variables(
+                        self.file,
+                        self.scopes.last().copied(),
+                        context,
+                        MAX_CONTEXT_DEPTH,
+                    )
+                })
+                .unwrap_or_default()
+                .into_boxed_slice(),
         })
     }
 
-    /// the names a dict literal binds
-    fn dict_variables(&self, expr: &Expr) -> Box<[ContextVariable]> {
-        let Expr::Dict(dict) = expr else {
-            return Box::default();
-        };
-
-        dict.items
-            .iter()
-            .filter_map(|item| {
-                let key = item.key.as_ref()?;
-                Some(ContextVariable {
-                    name: string_literal(key)?,
-                    file: self.file,
-                    range: key.range(),
-                    value: Some(item.value.range()),
-                })
-            })
-            .collect()
-    }
-
     /// the context a class-based view declares
     ///
     /// django's generic views name their template with `template_name` and their
@@ -2091,73 +2693,362 @@ impl ContextVisitor {
             .and_then(|(value, _)| string_literal(value))?;
 
         let mut variables = Vec::new();
+        let mut seen = Vec::new();
+        view_context(
+            self.db,
+            self.file,
+            class,
+            &mut variables,
+            &mut seen,
+            MAX_VIEW_DEPTH,
+        );
 
-        for statement in &class.body {
-            if let Some((value, range)) = class_attribute(statement, "context_object_name")
-                && let Some(name) = string_literal(value)
-            {
-                variables.push(ContextVariable {
+        Some(TemplateContext {
+            template,
+            variables: variables.into_boxed_slice(),
+        })
+    }
+}
+
+impl<'ast> Visitor<'ast> for ContextVisitor<'_, 'ast> {
+    fn visit_stmt(&mut self, stmt: &'ast Stmt) {
+        match stmt {
+            Stmt::ClassDef(class) => self.found.extend(self.class_based_view(class)),
+            Stmt::FunctionDef(function) => {
+                self.scopes.push(&function.body);
+                walk_stmt(self, stmt);
+                self.scopes.pop();
+            }
+            _ => walk_stmt(self, stmt),
+        }
+    }
+
+    fn visit_expr(&mut self, expr: &'ast Expr) {
+        if let Expr::Call(call) = expr {
+            self.found.extend(self.render_call(call));
+        }
+
+        walk_expr(self, expr);
+    }
+}
+
+/// everything a view class and the classes it inherits from put in the context
+///
+/// a base's `get_context_data` reaches every template its subclasses name, so the
+/// chain is walked. a class the walk has already read is not read again, and the
+/// walk is bounded: neither an inheritance chain read off the ast nor the
+/// resolution that follows it promises to be finite.
+fn view_context(
+    db: &dyn Db,
+    file: File,
+    class: &ast::StmtClassDef,
+    found: &mut Vec<ContextVariable>,
+    seen: &mut Vec<(File, TextRange)>,
+    depth: usize,
+) {
+    if depth == 0 || seen.contains(&(file, class.range())) {
+        return;
+    }
+    seen.push((file, class.range()));
+
+    declared_context(file, class, found);
+
+    for base in class.bases() {
+        resolved_class(db, file, base, |defining, base_class| {
+            view_context(db, defining, base_class, found, seen, depth - 1);
+        });
+    }
+}
+
+/// the names one view class's own body declares
+///
+/// a name the class declares itself outranks the same name from a base, exactly
+/// as it does at render time, so what is already found stays.
+fn declared_context(file: File, class: &ast::StmtClassDef, found: &mut Vec<ContextVariable>) {
+    for statement in &class.body {
+        if let Some((value, range)) = class_attribute(statement, CONTEXT_OBJECT_NAME_ATTRIBUTE)
+            && let Some(name) = string_literal(value)
+        {
+            merge_unseen(
+                found,
+                [ContextVariable {
                     name,
-                    file: self.file,
+                    file,
                     range,
                     // the object itself is what the view will bind; its type
                     // comes from the view's generics, which is beyond what a
                     // syntactic scan can follow
                     value: None,
-                });
-            }
+                    source: ContextSource::View,
+                }],
+            );
+        }
 
-            if let Some((value, _)) = class_attribute(statement, "extra_context") {
-                variables.extend(self.dict_variables(value));
+        if let Some((value, _)) = class_attribute(statement, EXTRA_CONTEXT_ATTRIBUTE) {
+            merge_unseen(
+                found,
+                context_variables(file, None, value, MAX_CONTEXT_DEPTH),
+            );
+        }
+
+        if let Stmt::FunctionDef(function) = statement
+            && function.name.as_str() == GET_CONTEXT_DATA_METHOD
+        {
+            merge_unseen(found, returned_context(file, &function.body));
+        }
+    }
+}
+
+/// the names the dict a `get_context_data` body returns holds
+///
+/// what it returns is read first, and every `context["name"] = …` of the body is
+/// taken on top of that: a body that hands its dict on to `super()` rather than
+/// returning it still writes the names it writes.
+fn returned_context(file: File, body: &[Stmt]) -> Vec<ContextVariable> {
+    let mut returns = ReturnVisitor { found: Vec::new() };
+    returns.visit_body(body);
+
+    let mut found = Vec::new();
+    for value in returns.found {
+        merge_unseen(
+            &mut found,
+            context_variables(file, Some(body), value, MAX_CONTEXT_DEPTH),
+        );
+    }
+
+    let mut writes = Vec::new();
+    let mut visitor = ContextAssignmentVisitor {
+        file,
+        found: &mut writes,
+    };
+    visitor.visit_body(body);
+
+    merge_unseen(&mut found, writes);
+    found
+}
+
+/// the names `expr` contributes to a context
+///
+/// a dict literal binds its keys. a name is followed to what the body that binds
+/// it holds there, which is the whole of the difference between a context written
+/// out in the `render()` call and the far commoner one built up above it. anything
+/// else — a call, a comprehension, a name with no body to look in — contributes
+/// nothing rather than a guess.
+fn context_variables(
+    file: File,
+    scope: Option<&[Stmt]>,
+    expr: &Expr,
+    fuel: usize,
+) -> Vec<ContextVariable> {
+    let mut found = Vec::new();
+
+    match expr {
+        Expr::Dict(dict) => {
+            for item in &dict.items {
+                match item.key.as_ref() {
+                    Some(key) => {
+                        let Some(name) = string_literal(key) else {
+                            continue;
+                        };
+                        merge_over(
+                            &mut found,
+                            ContextVariable {
+                                name,
+                                file,
+                                range: key.range(),
+                                value: Some(item.value.range()),
+                                source: ContextSource::View,
+                            },
+                        );
+                    }
+                    // `{**base, "extra": …}` spreads whatever `base` holds here
+                    None if fuel > 0 => {
+                        for variable in context_variables(file, scope, &item.value, fuel - 1) {
+                            merge_over(&mut found, variable);
+                        }
+                    }
+                    None => {}
+                }
             }
+        }
+        Expr::Name(name) if fuel > 0 => {
+            if let Some(scope) = scope {
+                found = bound_context(file, scope, name.id.as_str(), name.start(), fuel - 1);
+            }
+        }
+        _ => {}
+    }
 
-            if let Stmt::FunctionDef(function) = statement
-                && function.name.as_str() == "get_context_data"
-            {
-                variables.extend(self.context_assignments(&function.body));
+    found
+}
+
+/// what the local `name` holds by the time execution reaches `before`
+///
+/// the statements that build it are read in the order they are written: a
+/// rebinding replaces what came before it, a subscript write and an `update()`
+/// add to it. that is the dict `render()` is handed.
+fn bound_context(
+    file: File,
+    scope: &[Stmt],
+    name: &str,
+    before: TextSize,
+    fuel: usize,
+) -> Vec<ContextVariable> {
+    let mut mutations = MutationVisitor {
+        name,
+        before,
+        found: Vec::new(),
+    };
+    mutations.visit_body(scope);
+
+    let mut found = Vec::new();
+    for mutation in mutations.found {
+        match mutation {
+            Mutation::Bound(value) => {
+                found = context_variables(file, Some(scope), value, fuel);
+            }
+            Mutation::Extended(value) => {
+                for variable in context_variables(file, Some(scope), value, fuel) {
+                    merge_over(&mut found, variable);
+                }
+            }
+            Mutation::Wrote(key, value) => {
+                let Some(name) = string_literal(key) else {
+                    continue;
+                };
+                merge_over(
+                    &mut found,
+                    ContextVariable {
+                        name,
+                        file,
+                        range: key.range(),
+                        value: Some(value.range()),
+                        source: ContextSource::View,
+                    },
+                );
             }
         }
+    }
 
-        Some(TemplateContext {
-            template,
-            variables: variables.into_boxed_slice(),
-        })
+    found
+}
+
+/// add `variable`, replacing a name already there
+///
+/// a dict written twice over holds what was written last, and so does the
+/// context django renders with.
+fn merge_over(found: &mut Vec<ContextVariable>, variable: ContextVariable) {
+    match found
+        .iter_mut()
+        .find(|existing| existing.name == variable.name)
+    {
+        Some(existing) => *existing = variable,
+        None => found.push(variable),
     }
+}
 
-    /// the names a `get_context_data` body writes into its context dict
-    fn context_assignments(&self, body: &[Stmt]) -> Vec<ContextVariable> {
-        let mut found = Vec::new();
+/// add every name of `extra` that isn't spoken for already
+///
+/// where two independent sources name the same thing it is the first that wins,
+/// which is what puts a view's own declaration above the one it inherits.
+fn merge_unseen(
+    found: &mut Vec<ContextVariable>,
+    extra: impl IntoIterator<Item = ContextVariable>,
+) {
+    for variable in extra {
+        if !found.iter().any(|existing| existing.name == variable.name) {
+            found.push(variable);
+        }
+    }
+}
 
-        let mut visitor = ContextAssignmentVisitor {
-            file: self.file,
-            found: &mut found,
-        };
-        visitor.visit_body(body);
+/// one statement that builds up a context held in a variable
+enum Mutation<'ast> {
+    /// `context = value`, which replaces whatever it held
+    Bound(&'ast Expr),
+    /// `context.update(value)`
+    Extended(&'ast Expr),
+    /// `context["name"] = value`
+    Wrote(&'ast Expr, &'ast Expr),
+}
 
-        found
+/// collects, in the order written, what one function body does to one name
+struct MutationVisitor<'a, 'ast> {
+    name: &'a str,
+    /// where the context is read, past which nothing has run yet
+    before: TextSize,
+    found: Vec<Mutation<'ast>>,
+}
+
+impl MutationVisitor<'_, '_> {
+    /// whether `expr` is the name being followed
+    fn is_target(&self, expr: &Expr) -> bool {
+        matches!(expr, Expr::Name(name) if name.id.as_str() == self.name)
     }
 }
 
-impl<'ast> Visitor<'ast> for ContextVisitor {
+impl<'ast> Visitor<'ast> for MutationVisitor<'_, 'ast> {
     fn visit_stmt(&mut self, stmt: &'ast Stmt) {
-        if let Stmt::ClassDef(class) = stmt {
-            self.found.extend(self.class_based_view(class));
+        // a statement below the read has not run when the context is handed over,
+        // and one in a body of its own belongs to that body rather than to this
+        if stmt.start() >= self.before || matches!(stmt, Stmt::FunctionDef(_) | Stmt::ClassDef(_)) {
             return;
         }
 
-        walk_stmt(self, stmt);
+        match stmt {
+            Stmt::Assign(assign) => match assign.targets.as_slice() {
+                [target] if self.is_target(target) => {
+                    self.found.push(Mutation::Bound(&assign.value));
+                }
+                [Expr::Subscript(subscript)] if self.is_target(&subscript.value) => {
+                    self.found
+                        .push(Mutation::Wrote(&subscript.slice, &assign.value));
+                }
+                _ => {}
+            },
+            Stmt::AnnAssign(assign) => {
+                if self.is_target(&assign.target)
+                    && let Some(value) = assign.value.as_deref()
+                {
+                    self.found.push(Mutation::Bound(value));
+                }
+            }
+            Stmt::Expr(expression) => {
+                if let Expr::Call(call) = &*expression.value
+                    && let Expr::Attribute(attribute) = &*call.func
+                    && attribute.attr.as_str() == CONTEXT_UPDATE_METHOD
+                    && self.is_target(&attribute.value)
+                    && let [argument] = call.arguments.args.as_ref()
+                {
+                    self.found.push(Mutation::Extended(argument));
+                }
+            }
+            _ => walk_stmt(self, stmt),
+        }
     }
+}
 
-    fn visit_expr(&mut self, expr: &'ast Expr) {
-        if let Expr::Call(call) = expr {
-            self.found.extend(self.render_call(call));
-        }
+/// collects the value of every `return` of a body, its nested bodies apart
+struct ReturnVisitor<'ast> {
+    found: Vec<&'ast Expr>,
+}
 
-        walk_expr(self, expr);
+impl<'ast> Visitor<'ast> for ReturnVisitor<'ast> {
+    fn visit_stmt(&mut self, stmt: &'ast Stmt) {
+        match stmt {
+            // a nested function returns for itself, not for the body holding it
+            Stmt::FunctionDef(_) | Stmt::ClassDef(_) => {}
+            Stmt::Return(statement) => self.found.extend(statement.value.as_deref()),
+            _ => walk_stmt(self, stmt),
+        }
     }
 }
 
 /// collects `context["name"] = value` writes
+///
+/// the dict written into has to be a name of the body's own: a write to
+/// `request.session["cart"]` is a write to something that is not a context at
+/// all, and reading it as one would put a name in every template that has none.
 struct ContextAssignmentVisitor<'a> {
     file: File,
     found: &'a mut Vec<ContextVariable>,
@@ -2167,6 +3058,7 @@ impl<'ast> Visitor<'ast> for ContextAssignmentVisitor<'_> {
     fn visit_stmt(&mut self, stmt: &'ast Stmt) {
         if let Stmt::Assign(assign) = stmt
             && let [Expr::Subscript(subscript)] = assign.targets.as_slice()
+            && matches!(&*subscript.value, Expr::Name(_))
             && let Some(name) = string_literal(&subscript.slice)
         {
             self.found.push(ContextVariable {
@@ -2174,6 +3066,7 @@ impl<'ast> Visitor<'ast> for ContextAssignmentVisitor<'_> {
                 file: self.file,
                 range: subscript.slice.range(),
                 value: Some(assign.value.range()),
+                source: ContextSource::View,
             });
         }
 
@@ -2181,6 +3074,61 @@ impl<'ast> Visitor<'ast> for ContextAssignmentVisitor<'_> {
     }
 }
 
+/// every name a context processor puts in every template's context
+///
+/// `TEMPLATES[*]["OPTIONS"]["context_processors"]` names functions django calls
+/// on each render and merges the dict of into the context, so `request` and
+/// `user` are written in templates no view ever mentions them to.
+#[salsa::tracked(returns(ref), heap_size=ruff_memory_usage::heap_size)]
+pub(crate) fn context_processor_variables(db: &dyn Db, project: Project) -> Box<[ContextVariable]> {
+    let Some(importing) = *settings_file(db, project) else {
+        return Box::default();
+    };
+
+    // django merges each processor's dict over the ones before it, so where two
+    // of them name the same thing it is the last that renders
+    let mut found = Vec::new();
+    for processor in &django_settings(db, project).context_processors {
+        for variable in processor_variables(db, importing, processor) {
+            merge_over(&mut found, variable);
+        }
+    }
+
+    found.into_boxed_slice()
+}
+
+/// the names the processor the dotted `name` resolves to returns
+///
+/// only what a `return` of the function itself can be read as a dict is
+/// answered. a processor building its dict some other way — a comprehension, a
+/// call into something else — contributes nothing rather than a guessed name.
+fn processor_variables(db: &dyn Db, importing: File, name: &str) -> Vec<ContextVariable> {
+    let Some((module, function)) = name.rsplit_once('.') else {
+        return Vec::new();
+    };
+    // what a processor returns is only ever written in the module that runs
+    let Some(file) = ModuleName::new(module)
+        .and_then(|module| resolve_real_module(db, importing, &module))
+        .and_then(|module| module.file(db))
+    else {
+        return Vec::new();
+    };
+
+    let parsed = parsed_module(db, file).load(db);
+    let Some(definition) = parsed.suite().iter().find_map(|statement| match statement {
+        Stmt::FunctionDef(definition) if definition.name.as_str() == function => Some(definition),
+        _ => None,
+    }) else {
+        return Vec::new();
+    };
+
+    let mut found = returned_context(file, &definition.body);
+    for variable in &mut found {
+        variable.source = ContextSource::Processor;
+    }
+    found
+}
+
 /// the value and name range of a class-body assignment to `attribute`
 pub(crate) fn class_attribute<'ast>(
     statement: &'ast Stmt,
@@ -2248,8 +3196,8 @@ mod tests {
     use crate::django_template::tests::TemplateTest;
 
     use super::{
-        RegistrationKind, context_for_template, registrations, static_files, tag_libraries,
-        template_files, url_names,
+        RegistrationKind, context_for_template, context_processor_variables, registrations,
+        static_files, tag_libraries, template_files, url_names,
     };
 
     /// a project of python sources, with a throwaway template to anchor the
@@ -2326,6 +3274,14 @@ mod tests {
             .collect()
     }
 
+    /// the names the project's context processors put in every context
+    fn processors(test: &TemplateTest) -> Vec<String> {
+        context_processor_variables(&test.db, test.db.project())
+            .iter()
+            .map(|variable| variable.name.to_string())
+            .collect()
+    }
+
     #[test]
     fn a_class_based_view_contributes_every_name_it_declares() {
         let test = project(&[(
@@ -2404,6 +3360,323 @@ mod tests {
         assert_eq!(context(&test, "app/page.html"), ["book", "shelf", "author"]);
     }
 
+    #[test]
+    fn a_context_held_in_a_variable_is_followed_to_what_it_holds() {
+        let test = project(&[(
+            "app/views.py",
+            "
+            def show(request):
+                context = {'book': 1, 'shelf': 2}
+                return render(request, 'app/page.html', context)
+            ",
+        )]);
+
+        assert_eq!(context(&test, "app/page.html"), ["book", "shelf"]);
+    }
+
+    #[test]
+    fn a_context_is_followed_through_the_writes_and_updates_that_build_it() {
+        let test = project(&[(
+            "app/views.py",
+            "
+            def show(request):
+                context = {'book': 1}
+                context['extra'] = 2
+                context.update({'more': 3})
+                return render(request, 'app/page.html', context)
+            ",
+        )]);
+
+        assert_eq!(context(&test, "app/page.html"), ["book", "extra", "more"]);
+    }
+
+    #[test]
+    fn a_context_spread_from_another_dict_carries_its_names_too() {
+        let test = project(&[(
+            "app/views.py",
+            "
+            def show(request):
+                base = {'site': 1}
+                context = {**base, 'book': 2}
+                return render(request, 'app/page.html', context)
+            ",
+        )]);
+
+        assert_eq!(context(&test, "app/page.html"), ["site", "book"]);
+    }
+
+    #[test]
+    fn a_context_rebound_more_than_once_is_read_as_it_stands_at_the_render_call() {
+        let test = project(&[(
+            "app/views.py",
+            "
+            def show(request):
+                context = {'first': 1}
+                context = {'second': 2}
+                return render(request, 'app/page.html', context)
+            ",
+        )]);
+
+        assert_eq!(context(&test, "app/page.html"), ["second"]);
+    }
+
+    #[test]
+    fn two_renders_of_one_context_each_see_what_had_run_by_then() {
+        let test = project(&[(
+            "app/views.py",
+            "
+            def show(request):
+                context = {'book': 1}
+                if request.GET:
+                    return render(request, 'app/early.html', context)
+                context['extra'] = 2
+                return render(request, 'app/page.html', context)
+            ",
+        )]);
+
+        assert_eq!(context(&test, "app/early.html"), ["book"]);
+        assert_eq!(context(&test, "app/page.html"), ["book", "extra"]);
+    }
+
+    #[test]
+    fn a_context_that_cannot_be_followed_contributes_nothing() {
+        let test = project(&[(
+            "app/views.py",
+            "
+            def show(request):
+                context = build_context(request)
+                context['extra'] = 1
+                return render(request, 'app/page.html', context)
+            ",
+        )]);
+
+        // the call is unreadable, but the write on top of it is not
+        assert_eq!(context(&test, "app/page.html"), ["extra"]);
+    }
+
+    #[test]
+    fn a_context_bound_outside_the_rendering_function_is_not_followed() {
+        let test = project(&[(
+            "app/views.py",
+            "
+            context = {'book': 1}
+
+            def show(request):
+                return render(request, 'app/page.html', context)
+            ",
+        )]);
+
+        assert!(context(&test, "app/page.html").is_empty());
+    }
+
+    #[test]
+    fn a_base_class_contributes_the_context_it_builds() {
+        let test = project(&[(
+            "app/views.py",
+            "
+            class BaseView:
+                extra_context = {'year': 2026}
+
+                def get_context_data(self, **kwargs):
+                    context = super().get_context_data(**kwargs)
+                    context['site'] = 1
+                    return context
+
+            class BookView(BaseView):
+                template_name = 'app/detail.html'
+
+                def get_context_data(self, **kwargs):
+                    context = super().get_context_data(**kwargs)
+                    context['book'] = 2
+                    return context
+            ",
+        )]);
+
+        assert_eq!(
+            context(&test, "app/detail.html"),
+            ["book", "year", "site"],
+            "the view's own names come before the ones it inherits"
+        );
+    }
+
+    #[test]
+    fn a_base_class_in_another_module_contributes_too() {
+        let test = project(&[
+            (
+                "app/base.py",
+                "
+                class BaseView:
+                    def get_context_data(self, **kwargs):
+                        context = super().get_context_data(**kwargs)
+                        context['site'] = 1
+                        return context
+                ",
+            ),
+            (
+                "app/views.py",
+                "
+                from app.base import BaseView
+
+                class BookView(BaseView):
+                    template_name = 'app/detail.html'
+                ",
+            ),
+        ]);
+
+        assert_eq!(context(&test, "app/detail.html"), ["site"]);
+    }
+
+    #[test]
+    fn a_class_that_inherits_in_a_circle_is_read_once_and_terminates() {
+        let test = project(&[(
+            "app/views.py",
+            "
+            class First(Second):
+                template_name = 'app/detail.html'
+                extra_context = {'first': 1}
+
+            class Second(First):
+                extra_context = {'second': 2}
+            ",
+        )]);
+
+        assert_eq!(context(&test, "app/detail.html"), ["first", "second"]);
+    }
+
+    #[test]
+    fn a_get_context_data_returning_a_dict_outright_contributes_its_keys() {
+        let test = project(&[(
+            "app/views.py",
+            "
+            class BookView:
+                template_name = 'app/detail.html'
+
+                def get_context_data(self, **kwargs):
+                    return {'book': 1, **super().get_context_data(**kwargs)}
+            ",
+        )]);
+
+        assert_eq!(context(&test, "app/detail.html"), ["book"]);
+    }
+
+    #[test]
+    fn a_context_processor_contributes_the_names_it_returns() {
+        let test = configured(
+            "
+            TEMPLATES = [{'OPTIONS': {'context_processors': ['app.processors.branding']}}]
+            ",
+            &[(
+                "app/processors.py",
+                "
+                def branding(request):
+                    return {'site_name': 'a blog', 'year': 2026}
+                ",
+            )],
+        );
+
+        assert_eq!(processors(&test), ["site_name", "year"]);
+    }
+
+    #[test]
+    fn a_context_processor_is_followed_through_the_variable_it_builds() {
+        let test = configured(
+            "
+            TEMPLATES = [{'OPTIONS': {'context_processors': ['app.processors.branding']}}]
+            ",
+            &[(
+                "app/processors.py",
+                "
+                def branding(request):
+                    context = {'site_name': 'a blog'}
+                    context['year'] = 2026
+                    return context
+                ",
+            )],
+        );
+
+        assert_eq!(processors(&test), ["site_name", "year"]);
+    }
+
+    #[test]
+    fn a_context_processor_whose_result_cannot_be_read_contributes_nothing() {
+        let test = configured(
+            "
+            TEMPLATES = [{'OPTIONS': {'context_processors': [
+                'app.processors.built',
+                'app.processors.elsewhere',
+                'app.processors.missing',
+                'nowhere.at_all',
+            ]}}]
+            ",
+            &[(
+                "app/processors.py",
+                "
+                def built(request):
+                    return dict(site_name='a blog')
+
+                def elsewhere(request):
+                    return other(request)
+                ",
+            )],
+        );
+
+        assert!(processors(&test).is_empty());
+    }
+
+    #[test]
+    fn a_processor_writing_into_something_that_is_not_a_context_contributes_nothing() {
+        let test = configured(
+            "
+            TEMPLATES = [{'OPTIONS': {'context_processors': ['app.processors.branding']}}]
+            ",
+            &[(
+                "app/processors.py",
+                "
+                def branding(request):
+                    request.session['cart'] = []
+                    return {'site_name': 'a blog'}
+                ",
+            )],
+        );
+
+        assert_eq!(processors(&test), ["site_name"]);
+    }
+
+    #[test]
+    fn the_last_context_processor_to_name_something_is_the_one_that_renders() {
+        let test = configured(
+            "
+            TEMPLATES = [{'OPTIONS': {'context_processors': [
+                'app.processors.first',
+                'app.processors.second',
+            ]}}]
+            ",
+            &[(
+                "app/processors.py",
+                "
+                def first(request):
+                    return {'site_name': 'one'}
+
+                def second(request):
+                    return {'site_name': 'two'}
+                ",
+            )],
+        );
+
+        let found = context_processor_variables(&test.db, test.db.project());
+        assert_eq!(found.len(), 1);
+        assert_eq!(
+            &ruff_db::source::source_text(&test.db, found[0].file)[found[0].value.unwrap()],
+            "'two'"
+        );
+    }
+
+    #[test]
+    fn a_project_that_names_no_context_processors_has_none() {
+        let test = configured("TEMPLATES = [{'APP_DIRS': True}]", &[]);
+        assert!(processors(&test).is_empty());
+    }
+
     #[test]
     fn a_view_module_that_renders_nothing_is_not_parsed_for_contexts() {
         // the gate that skips it must not skip a file that does render
diff --git a/crates/ty_ide/src/django_template/python.rs b/crates/ty_ide/src/django_template/python.rs
index f222fa21fc..473b1fcab7 100644
--- a/crates/ty_ide/src/django_template/python.rs
+++ b/crates/ty_ide/src/django_template/python.rs
@@ -27,7 +27,7 @@ use super::project::{
 
 /// what a string literal in a python module names
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
-enum Names {
+pub(super) enum Names {
     /// a template, under the name its loader knows it by
     Template,
     /// a route of the project's url configuration
@@ -87,15 +87,15 @@ pub(crate) fn string_completions<'a>(
     }
 }
 
-/// where the django name the string literal at `offset` spells is defined
-pub(crate) fn string_definition(
-    db: &dyn Db,
-    file: File,
+/// what the string literal at `offset` names, with its value and its contents range
+///
+/// every request that comes through here would otherwise walk the tree for a
+/// position that is plainly not a string, which is a cost the whole crate would
+/// pay for django, so the token stream settles that first.
+pub(super) fn name_at(
     parsed: &ParsedModuleRef,
     offset: TextSize,
-) -> Option<RangedValue<NavigationTargets>> {
-    // every goto request comes through here, and walking the tree for a position
-    // that is plainly not a string would be a cost the whole crate pays for django
+) -> Option<(Names, CompactString, TextRange)> {
     if !parsed
         .tokens()
         .at_offset(offset)
@@ -107,7 +107,19 @@ pub(crate) fn string_definition(
     let covering = covering_node(parsed.syntax().into(), TextRange::empty(offset));
     let (string, names) = named(covering.ancestors())?;
     let range = contents(string)?;
-    let value = string.value.to_str();
+
+    Some((names, string.value.to_str().into(), range))
+}
+
+/// where the django name the string literal at `offset` spells is defined
+pub(crate) fn string_definition(
+    db: &dyn Db,
+    file: File,
+    parsed: &ParsedModuleRef,
+    offset: TextSize,
+) -> Option<RangedValue<NavigationTargets>> {
+    let (names, value, range) = name_at(parsed, offset)?;
+    let value = value.as_str();
 
     let targets: NavigationTargets = match names {
         Names::Template => NavigationTargets::from_iter([NavigationTarget::new(
diff --git a/crates/ty_ide/src/django_template/references.rs b/crates/ty_ide/src/django_template/references.rs
new file mode 100644
index 0000000000..8ce8ff5378
--- /dev/null
+++ b/crates/ty_ide/src/django_template/references.rs
@@ -0,0 +1,625 @@
+//! find-all-references for the django names written in two languages
+//!
+//! this is the direction the rest of the template services do not go. goto takes
+//! a name to the one place it is declared; this takes a declaration to every
+//! place it is used — which is the question you actually have when you are
+//! editing a base template and want to know which children override the block
+//! under the cursor, or whether anything still renders the file you are looking
+//! at.
+//!
+//! the scans are [`super::uses`]', shared with the rename that has to find the
+//! same occurrences. what this adds is the opposite temperament: a rename refuses
+//! over a use it could not rewrite, and this *reports* one, since knowing where a
+//! name is mentioned is useful whether or not a rewrite could reach it. the one
+//! thing left out is a name worked out at run time, which is no occurrence of
+//! this name so much as a position that might be one.
+
+use ruff_db::files::File;
+use ruff_text_size::TextSize;
+use ty_project::Db;
+
+use crate::{ReferenceKind, ReferenceTarget};
+
+use super::resolve;
+use super::uses::{self, Anchor, Named, Use, Written};
+
+/// every place the django name at `offset` of `file` is written
+///
+/// `template` says the file is a django template rather than python, which the
+/// caller knows and this cannot. a position in a template that names nothing in
+/// particular is answered for the template *file*: "what renders this" is the
+/// other question worth asking of a template, and a request anywhere in one is a
+/// reasonable way to ask it.
+pub(super) fn references(
+    db: &dyn Db,
+    file: File,
+    offset: TextSize,
+    include_declaration: bool,
+    template: bool,
+) -> Option<Vec<ReferenceTarget>> {
+    let named = uses::named_at(db, file, offset, template);
+
+    let mut found = match &named {
+        Some((Named::Block(name), _)) => uses::block(db, file, name).found,
+        Some((Named::Route(name), _)) => {
+            uses::route(db, &Anchor::Use { name: name.clone() })
+                .uses
+                .found
+        }
+        Some((Named::RouteDeclaration, range)) => {
+            uses::route(
+                db,
+                &Anchor::Declaration {
+                    file,
+                    range: *range,
+                },
+            )
+            .uses
+            .found
+        }
+        Some((Named::Template(name), _)) => uses::template(db, name).uses.found,
+        Some((Named::Tag(name), _)) => uses::registration(db, name, false).found,
+        Some((Named::Filter(name), _)) => uses::registration(db, name, true).found,
+        None => Vec::new(),
+    };
+
+    // a builtin tag is registered nowhere and written everywhere, so it finds
+    // nothing — and a position that names nothing at all finds nothing either.
+    // both leave the file itself as what the request is about
+    if found.is_empty() {
+        if !template {
+            return None;
+        }
+        found = uses::template(db, &resolve::template_name(db, file)?)
+            .uses
+            .found;
+    }
+
+    Some(targets(db, found, include_declaration))
+}
+
+/// the uses an editor is shown, in a stable order
+fn targets(db: &dyn Db, mut found: Vec<Use>, include_declaration: bool) -> Vec<ReferenceTarget> {
+    uses::sort(db, &mut found);
+    found.dedup_by(|left, right| (left.file, left.range) == (right.file, right.range));
+
+    found
+        .into_iter()
+        // a position that works its name out at run time writes no name to
+        // report. everything else does, whether or not a rename could rewrite it
+        .filter(|used| !matches!(used.written, Written::Unknown))
+        .filter(|used| include_declaration || !used.declaration)
+        .map(|used| {
+            let kind = if used.declaration {
+                ReferenceKind::Other
+            } else {
+                ReferenceKind::Read
+            };
+
+            ReferenceTarget::new(used.file, used.range, kind)
+        })
+        .collect()
+}
+
+#[cfg(test)]
+mod tests {
+    use crate::django_template::tests::TemplateTest;
+
+    /// a whole django project, with `sources` written into it
+    fn project(sources: &[(&str, &str)]) -> TemplateTest {
+        let mut all: Vec<(&str, &str)> = vec![
+            (
+                "manage.py",
+                "
+                import os
+
+                os.environ.setdefault('DJANGO_SETTINGS_MODULE', 'project.settings')
+                ",
+            ),
+            ("project/__init__.py", ""),
+            (
+                "project/settings.py",
+                "
+                INSTALLED_APPS = ['blog']
+
+                TEMPLATES = [{'DIRS': [], 'APP_DIRS': True, 'OPTIONS': {}}]
+
+                ROOT_URLCONF = 'project.urls'
+                ",
+            ),
+            (
+                "project/urls.py",
+                "
+                from django.urls import include, path
+
+                urlpatterns = [path('blog/', include('blog.urls'))]
+                ",
+            ),
+            ("blog/__init__.py", ""),
+            (
+                "blog/urls.py",
+                "
+                from django.urls import path
+
+                app_name = 'blog'
+
+                urlpatterns = [path('<int:pk>/', detail, name='detail')]
+                ",
+            ),
+        ];
+        all.extend_from_slice(sources);
+
+        TemplateTest::with_site_packages(&all, &[])
+    }
+
+    // -----------------------------------------------------------------------
+    // a `{% block %}` name
+    // -----------------------------------------------------------------------
+
+    /// `base` and three children, two overriding `content` and one `footer`
+    fn family(base: &str, cursor: &[(&str, &str)]) -> TemplateTest {
+        let mut all: Vec<(&str, &str)> = vec![
+            ("blog/templates/blog/base.html", base),
+            (
+                "blog/templates/blog/post.html",
+                "{% extends 'blog/base.html' %}{% block content %}a{% endblock content %}",
+            ),
+            (
+                "blog/templates/blog/list.html",
+                "{% extends 'blog/base.html' %}{% block content %}b{% endblock %}",
+            ),
+            (
+                "blog/templates/blog/sidebar.html",
+                "{% extends 'blog/base.html' %}{% block footer %}c{% endblock %}",
+            ),
+        ];
+        all.extend_from_slice(cursor);
+
+        project(&all)
+    }
+
+    #[test]
+    fn a_block_in_the_base_finds_every_child_that_overrides_it() {
+        let test = family(
+            "{% block co<CURSOR>ntent %}{% endblock %}{% block footer %}{% endblock %}",
+            &[],
+        );
+
+        assert_eq!(
+            test.references(),
+            [
+                "declaration /src/blog/templates/blog/base.html:1 content",
+                "/src/blog/templates/blog/list.html:1 content",
+                "/src/blog/templates/blog/post.html:1 content",
+                "/src/blog/templates/blog/post.html:1 content",
+            ]
+        );
+    }
+
+    #[test]
+    fn a_block_in_a_child_finds_the_base_and_its_siblings() {
+        let test = family(
+            "{% block content %}{% endblock %}{% block footer %}{% endblock %}",
+            &[(
+                "blog/templates/blog/edit.html",
+                "{% extends 'blog/base.html' %}{% block co<CURSOR>ntent %}d{% endblock %}",
+            )],
+        );
+        let found = test.references();
+
+        assert!(
+            found.contains(&"declaration /src/blog/templates/blog/base.html:1 content".to_string()),
+            "got {found:?}"
+        );
+        assert!(
+            found.contains(&"/src/blog/templates/blog/list.html:1 content".to_string()),
+            "got {found:?}"
+        );
+        assert!(
+            !found.iter().any(|target| target.contains("sidebar")),
+            "a sibling overriding another block is no use of this one: got {found:?}"
+        );
+    }
+
+    #[test]
+    fn leaving_the_declaration_out_leaves_the_base_out() {
+        let test = family("{% block co<CURSOR>ntent %}{% endblock %}", &[]);
+
+        assert_eq!(
+            test.references_without_declaration(),
+            [
+                "/src/blog/templates/blog/list.html:1 content",
+                "/src/blog/templates/blog/post.html:1 content",
+                "/src/blog/templates/blog/post.html:1 content",
+            ]
+        );
+    }
+
+    #[test]
+    fn a_block_is_still_found_where_a_rename_would_refuse() {
+        // an installed app's template overriding the block refuses the rename,
+        // since it is not the project's to rewrite — but it is exactly what
+        // someone editing the base wants to be shown
+        let test = TemplateTest::with_site_packages(
+            &[
+                (
+                    "manage.py",
+                    "
+                    import os
+
+                    os.environ.setdefault('DJANGO_SETTINGS_MODULE', 'project.settings')
+                    ",
+                ),
+                ("project/__init__.py", ""),
+                (
+                    "project/settings.py",
+                    "
+                    INSTALLED_APPS = ['blog', 'widgets']
+
+                    TEMPLATES = [{'DIRS': [], 'APP_DIRS': True, 'OPTIONS': {}}]
+                    ",
+                ),
+                ("blog/__init__.py", ""),
+                (
+                    "blog/templates/blog/base.html",
+                    "{% block co<CURSOR>ntent %}{% endblock %}",
+                ),
+            ],
+            &[
+                ("widgets/__init__.py", ""),
+                (
+                    "widgets/templates/widgets/panel.html",
+                    "{% extends 'blog/base.html' %}{% block content %}x{% endblock %}",
+                ),
+            ],
+        );
+
+        assert_eq!(
+            test.prepare_rename(),
+            "refused: `/site-packages/widgets/templates/widgets/panel.html` declares this block \
+             too, and an installed app's template is not the project's to rewrite"
+        );
+        assert_eq!(
+            test.references(),
+            [
+                "/site-packages/widgets/templates/widgets/panel.html:1 content",
+                "declaration /src/blog/templates/blog/base.html:1 content",
+            ]
+        );
+    }
+
+    // -----------------------------------------------------------------------
+    // a template
+    // -----------------------------------------------------------------------
+
+    /// the same project, with a view and a template that several things load
+    fn loaded(post: &str) -> TemplateTest {
+        project(&[
+            (
+                "blog/views.py",
+                "
+                from django.shortcuts import render
+
+
+                def post(request):
+                    return render(request, 'blog/post.html', {})
+
+
+                class PostView:
+                    template_name = 'blog/post.html'
+                ",
+            ),
+            (
+                "blog/templates/blog/list.html",
+                "{% include 'blog/post.html' %}",
+            ),
+            ("blog/templates/blog/post.html", post),
+        ])
+    }
+
+    #[test]
+    fn a_template_is_found_from_a_position_that_names_nothing_in_it() {
+        let test = loaded("<p>a p<CURSOR>ost</p>");
+
+        assert_eq!(
+            test.references(),
+            [
+                "/src/blog/templates/blog/list.html:1 blog/post.html",
+                "declaration /src/blog/templates/blog/post.html:1 ",
+                "/src/blog/views.py:6 blog/post.html",
+                "/src/blog/views.py:10 blog/post.html",
+            ]
+        );
+    }
+
+    #[test]
+    fn a_template_named_in_an_include_is_found_from_the_name_itself() {
+        let test = project(&[
+            (
+                "blog/templates/blog/list.html",
+                "{% include 'blog/po<CURSOR>st.html' %}",
+            ),
+            ("blog/templates/blog/post.html", "x"),
+        ]);
+
+        assert_eq!(
+            test.references_without_declaration(),
+            ["/src/blog/templates/blog/list.html:1 blog/post.html"]
+        );
+    }
+
+    #[test]
+    fn a_template_is_found_from_the_render_that_names_it_in_python() {
+        let test = loaded("x");
+
+        assert_eq!(
+            test.references(),
+            [
+                "/src/blog/templates/blog/list.html:1 blog/post.html",
+                "declaration /src/blog/templates/blog/post.html:1 ",
+                "/src/blog/views.py:6 blog/post.html",
+                "/src/blog/views.py:10 blog/post.html",
+            ]
+        );
+    }
+
+    #[test]
+    fn a_constant_holding_a_templates_name_is_reported_rather_than_refused() {
+        // a rename stops at a constant, since it cannot follow where one carries
+        // the name — which is the very reason to show it
+        let test = project(&[
+            (
+                "blog/tasks.py",
+                "
+                WELCOME = 'blog/post.html'
+
+
+                def send(request):
+                    return render(request, WELCOME, {})
+                ",
+            ),
+            (
+                "blog/templates/blog/child.html",
+                "{% extends 'blog/p<CURSOR>ost.html' %}",
+            ),
+            ("blog/templates/blog/post.html", "x"),
+        ]);
+
+        assert!(
+            test.prepare_rename()
+                .contains("binds this name to `WELCOME`"),
+            "got {}",
+            test.prepare_rename()
+        );
+        assert_eq!(
+            test.references_without_declaration(),
+            [
+                "/src/blog/tasks.py:2 blog/post.html",
+                "/src/blog/templates/blog/child.html:1 blog/post.html",
+            ]
+        );
+    }
+
+    #[test]
+    fn a_template_nothing_loads_is_found_only_as_itself() {
+        let test = project(&[("blog/templates/blog/post.html", "<p>a p<CURSOR>ost</p>")]);
+
+        assert_eq!(
+            test.references(),
+            ["declaration /src/blog/templates/blog/post.html:1 "]
+        );
+        assert!(test.references_without_declaration().is_empty());
+    }
+
+    // -----------------------------------------------------------------------
+    // a route name
+    // -----------------------------------------------------------------------
+
+    /// the same project, with a route reversed from both languages
+    fn reversed(sources: &[(&str, &str)]) -> TemplateTest {
+        let mut all: Vec<(&str, &str)> = vec![
+            (
+                "blog/views.py",
+                "
+                from django.urls import reverse, reverse_lazy
+
+
+                def go(request):
+                    reverse('blog:detail')
+                    reverse_lazy('blog:detail')
+                    return redirect('blog:detail')
+                ",
+            ),
+            (
+                "blog/templates/blog/nav.html",
+                "{% url 'blog:detail' pk=1 %}",
+            ),
+        ];
+        all.extend_from_slice(sources);
+
+        project(&all)
+    }
+
+    #[test]
+    fn a_route_is_found_from_a_url_tag_in_both_languages() {
+        let test = reversed(&[(
+            "blog/templates/blog/post.html",
+            "{% url 'blog:de<CURSOR>tail' %}",
+        )]);
+
+        assert_eq!(
+            test.references(),
+            [
+                "/src/blog/templates/blog/nav.html:1 blog:detail",
+                "/src/blog/templates/blog/post.html:1 blog:detail",
+                "declaration /src/blog/urls.py:6 detail",
+                "/src/blog/views.py:6 blog:detail",
+                "/src/blog/views.py:7 blog:detail",
+                "/src/blog/views.py:8 blog:detail",
+            ]
+        );
+    }
+
+    #[test]
+    fn a_route_is_found_from_its_own_declaration() {
+        let test = project(&[
+            (
+                "blog/urls.py",
+                "
+                from django.urls import path
+
+                app_name = 'blog'
+
+                urlpatterns = [path('<int:pk>/', detail, name='de<CURSOR>tail')]
+                ",
+            ),
+            (
+                "blog/templates/blog/nav.html",
+                "{% url 'blog:detail' pk=1 %}",
+            ),
+        ]);
+
+        assert_eq!(
+            test.references_without_declaration(),
+            ["/src/blog/templates/blog/nav.html:1 blog:detail"]
+        );
+    }
+
+    #[test]
+    fn a_route_is_found_from_a_reverse_in_python() {
+        let test = project(&[
+            (
+                "blog/templates/blog/nav.html",
+                "{% url 'blog:detail' pk=1 %}",
+            ),
+            (
+                "blog/views.py",
+                "
+                from django.urls import reverse
+
+
+                def go(request):
+                    return reverse('blog:de<CURSOR>tail')
+                ",
+            ),
+        ]);
+
+        assert_eq!(
+            test.references(),
+            [
+                "/src/blog/templates/blog/nav.html:1 blog:detail",
+                "declaration /src/blog/urls.py:6 detail",
+                "/src/blog/views.py:6 blog:detail",
+            ]
+        );
+    }
+
+    #[test]
+    fn a_route_reversed_at_run_time_is_no_use_of_this_one() {
+        // it names *some* route, and a rename refuses over exactly that — but a
+        // position that spells no name is no place this name is mentioned
+        let test = reversed(&[
+            (
+                "blog/report.py",
+                "
+                from django.urls import reverse
+
+
+                def go(request, wanted):
+                    return reverse(wanted)
+                ",
+            ),
+            (
+                "blog/templates/blog/post.html",
+                "{% url 'blog:de<CURSOR>tail' %}",
+            ),
+        ]);
+
+        assert!(
+            test.prepare_rename().contains("worked out at run time"),
+            "got {}",
+            test.prepare_rename()
+        );
+        assert!(
+            !test
+                .references()
+                .iter()
+                .any(|target| target.contains("report.py")),
+            "got {:?}",
+            test.references()
+        );
+    }
+
+    // -----------------------------------------------------------------------
+    // a tag or filter name
+    // -----------------------------------------------------------------------
+
+    /// the same project with a tag library, and a template using both of its
+    /// registrations
+    fn library(post: &str) -> TemplateTest {
+        project(&[
+            (
+                "blog/templatetags/blog_extras.py",
+                "
+                from django import template
+
+                register = template.Library()
+
+
+                @register.filter
+                def shout(value):
+                    return value
+
+
+                @register.simple_tag
+                def book_count():
+                    return 0
+                ",
+            ),
+            (
+                "blog/templates/blog/nav.html",
+                "{% load blog_extras %}{% book_count %}{{ x|shout }}",
+            ),
+            ("blog/templates/blog/post.html", post),
+        ])
+    }
+
+    #[test]
+    fn a_tag_is_found_in_every_template_that_uses_it() {
+        let test = library("{% load blog_extras %}{% book_c<CURSOR>ount %}");
+
+        assert_eq!(
+            test.references(),
+            [
+                "/src/blog/templates/blog/nav.html:1 book_count",
+                "/src/blog/templates/blog/post.html:1 book_count",
+                "declaration /src/blog/templatetags/blog_extras.py:13 book_count",
+            ]
+        );
+    }
+
+    #[test]
+    fn a_filter_is_found_in_every_template_that_uses_it() {
+        let test = library("{% load blog_extras %}{{ y|sho<CURSOR>ut }}");
+
+        assert_eq!(
+            test.references_without_declaration(),
+            [
+                "/src/blog/templates/blog/nav.html:1 shout",
+                "/src/blog/templates/blog/post.html:1 shout",
+            ]
+        );
+    }
+
+    #[test]
+    fn a_builtin_tag_answers_for_the_file_it_is_written_in() {
+        // nothing registers `{% if %}`, and every `{% if %}` in a project is no
+        // answer to any question — so the file itself is what is left to answer for
+        let test = library("{% i<CURSOR>f x %}{% endif %}");
+
+        assert_eq!(
+            test.references(),
+            ["declaration /src/blog/templates/blog/post.html:1 "]
+        );
+    }
+}
diff --git a/crates/ty_ide/src/django_template/rename.rs b/crates/ty_ide/src/django_template/rename.rs
new file mode 100644
index 0000000000..f6b2cab864
--- /dev/null
+++ b/crates/ty_ide/src/django_template/rename.rs
@@ -0,0 +1,1535 @@
+//! renaming the django names that are written in two languages
+//!
+//! a `{% block %}` name is written in the template that declares it and in every
+//! template that overrides it; a route name in the `path()` that declares it and
+//! in every `{% url %}` and `reverse()` that reaches it; a template name in every
+//! `{% extends %}`, `{% include %}` and `render()` that loads it, and in the name
+//! of the file itself. renaming any of them by hand means finding all the others
+//! by hand, which is what makes this worth doing — and what makes it dangerous.
+//! a rename that misses one occurrence leaves a project that no longer renders,
+//! and nothing about the result looks wrong.
+//!
+//! so every path through this module ends in one of two places: a complete set of
+//! edits, or a refusal that says why. an index that does not answer for the whole
+//! project, an inheritance tree with a gap in it, a name written in a form
+//! nothing here could rewrite — each of those refuses the whole rename rather
+//! than applying the visible part of it.
+//!
+//! finding the occurrences is [`super::uses`]' job, which references asks the same
+//! question of. this module is what turns each of them into an edit or into the
+//! refusal it is evidence for; the limit that leaves is a name assembled at run
+//! time out of pieces — `f"blog:{kind}"`, `"blog/" + page` — which spells nothing
+//! anything can see.
+
+use compact_str::{CompactString, ToCompactString};
+use ruff_db::files::{File, FileRange};
+use ruff_db::source::source_text;
+use ruff_db::system::SystemPathBuf;
+use ruff_text_size::{Ranged, TextRange, TextSize};
+use ty_project::Db;
+
+use super::project::{self, NAMESPACE_SEPARATOR};
+use super::uses::{self, Anchor, FRAGMENT_SEPARATOR, Named, Use, Written};
+
+/// what renaming a django name would do
+#[derive(Debug, PartialEq, Eq)]
+pub struct TemplateRename {
+    /// every range whose text the new name replaces
+    pub edits: Vec<FileRange>,
+    /// the template file to move, and the path it moves to
+    pub file_rename: Option<(SystemPathBuf, SystemPathBuf)>,
+}
+
+/// what the editor should offer for a rename at a position
+#[derive(Debug, PartialEq, Eq)]
+pub enum PreparedTemplateRename {
+    /// the range the editor offers, and the text it starts as
+    Ready {
+        range: TextRange,
+        placeholder: String,
+    },
+    /// why the rename cannot be done
+    Refused(String),
+}
+
+/// the answer to a rename request
+#[derive(Debug, PartialEq, Eq)]
+pub enum TemplateRenameOutcome {
+    Edits(TemplateRename),
+    /// why the rename cannot be done
+    Refused(String),
+}
+
+/// whether the name at `offset` can be renamed, and what the editor should offer
+///
+/// `None` is a position that names nothing django knows, which is what leaves the
+/// python services to answer for it.
+pub(super) fn prepare(
+    db: &dyn Db,
+    file: File,
+    offset: TextSize,
+    template: bool,
+) -> Option<PreparedTemplateRename> {
+    Some(match plan(db, file, offset, template)? {
+        Ok(plan) => PreparedTemplateRename::Ready {
+            range: plan.range,
+            placeholder: plan.placeholder.to_string(),
+        },
+        Err(refusal) => PreparedTemplateRename::Refused(refusal),
+    })
+}
+
+/// every edit renaming the name at `offset` to `new_name` would make
+pub(super) fn rename(
+    db: &dyn Db,
+    file: File,
+    offset: TextSize,
+    new_name: &str,
+    template: bool,
+) -> Option<TemplateRenameOutcome> {
+    Some(match plan(db, file, offset, template)? {
+        Ok(plan) => match plan.finish(db, new_name) {
+            Ok(rename) => TemplateRenameOutcome::Edits(rename),
+            Err(refusal) => TemplateRenameOutcome::Refused(refusal),
+        },
+        Err(refusal) => TemplateRenameOutcome::Refused(refusal),
+    })
+}
+
+/// what a rename at a position would touch, worked out before a new name is known
+///
+/// everything that decides whether the rename is possible at all is settled here,
+/// so that `prepareRename` refuses exactly what `rename` would.
+struct Plan {
+    /// the range the editor offers, in the file the request came from
+    range: TextRange,
+    placeholder: CompactString,
+    edits: Vec<FileRange>,
+    kind: Kind,
+}
+
+/// what is being renamed, and what settling on a new name still needs
+enum Kind {
+    /// the templates that declare the block, which is where a name already taken
+    /// would collide
+    Block {
+        declaring: Vec<File>,
+    },
+    Route,
+    /// the file to move, and the directory its name is relative to
+    Template {
+        path: SystemPathBuf,
+        root: SystemPathBuf,
+    },
+}
+
+fn plan(db: &dyn Db, file: File, offset: TextSize, template: bool) -> Option<Result<Plan, String>> {
+    let (named, range) = uses::named_at(db, file, offset, template)?;
+
+    Some(match named {
+        Named::Block(name) => block_plan(db, file, &name, range),
+        Named::Route(name) => route_plan(db, &Anchor::Use { name }, range),
+        Named::RouteDeclaration => route_plan(db, &Anchor::Declaration { file, range }, range),
+        Named::Template(name) => template_plan(db, &name, range),
+        // a tag and a filter are named by the python that registers them, which is
+        // the python rename's to carry out rather than this one's
+        Named::Tag(_) | Named::Filter(_) => return None,
+    })
+}
+
+// ---------------------------------------------------------------------------
+// a `{% block %}` name
+// ---------------------------------------------------------------------------
+
+fn block_plan(db: &dyn Db, file: File, name: &str, range: TextRange) -> Result<Plan, String> {
+    let found = uses::block(db, file, name);
+    if let Some(refusal) = found.incomplete {
+        return Err(refusal);
+    }
+
+    // an installed app's template overriding this block would have to be rewritten
+    // with the rest, and it is not the project's to rewrite
+    if let Some(installed) = found.found.iter().find(|used| !used.own) {
+        return Err(format!(
+            "`{}` declares this block too, and an installed app's template is not the project's \
+             to rewrite",
+            uses::path_of(db, installed.file)
+        ));
+    }
+
+    let mut declaring: Vec<File> = found.found.iter().map(|used| used.file).collect();
+    declaring.dedup();
+    // a clash the request's own template already holds is the one to say so about
+    declaring.sort_by_key(|member| *member != file);
+
+    let edits = found
+        .found
+        .iter()
+        .map(|used| FileRange::new(used.file, used.range))
+        .collect();
+
+    Ok(Plan {
+        range,
+        placeholder: name.to_compact_string(),
+        edits,
+        kind: Kind::Block { declaring },
+    })
+}
+
+// ---------------------------------------------------------------------------
+// a route name
+// ---------------------------------------------------------------------------
+
+fn route_plan(db: &dyn Db, anchor: &Anchor, range: TextRange) -> Result<Plan, String> {
+    let route = uses::route(db, anchor);
+    if let Some(refusal) = route.uses.incomplete {
+        return Err(refusal);
+    }
+    // every way a route can fail to be pinned down to one declaration is one
+    // `incomplete` has already refused over
+    let Some(declared) = route.declared else {
+        return Err("this route has no one declaration of its own".to_string());
+    };
+
+    if !declared.exact {
+        return Err(
+            "this route's name is generated from a rest framework router's basename rather than \
+             written out, so renaming it would mean renaming the basename and every route \
+             generated from it"
+                .to_string(),
+        );
+    }
+
+    let Some(bare) = declared.name else {
+        return Err(
+            "the route's name is not written as one plain string literal, so it cannot be \
+             rewritten"
+                .to_string(),
+        );
+    };
+    if !fits(declared.range, &bare) {
+        return Err(
+            "the route's name is written with an escape, so the name inside the literal cannot \
+             be located"
+                .to_string(),
+        );
+    }
+
+    let qualifier = format!("{NAMESPACE_SEPARATOR}{bare}");
+    if !route
+        .names
+        .iter()
+        .all(|name| *name == bare || name.ends_with(&qualifier))
+    {
+        return Err(format!(
+            "`{bare}` is reversed under a name that does not end in it, so the two cannot be \
+             renamed together"
+        ));
+    }
+
+    let mut edits = Vec::new();
+    let names: Vec<&str> = route.names.iter().map(CompactString::as_str).collect();
+
+    for used in &route.uses.found {
+        match &used.written {
+            Written::Whole if used.declaration => edits.push(FileRange::new(used.file, used.range)),
+            Written::Whole if used.own => {
+                edits.push(FileRange::new(
+                    used.file,
+                    replaced(db, used, &names, &bare)?,
+                ));
+            }
+            Written::Whole => {
+                return Err(format!(
+                    "{} reverses this route, and an installed app's template is not the \
+                     project's to rewrite",
+                    position(db, used.file, used.range)
+                ));
+            }
+            Written::Pieces => {
+                return Err(format!(
+                    "{} reverses this route under a name written in two pieces, which no one \
+                     range could replace",
+                    position(db, used.file, used.range)
+                ));
+            }
+            Written::Unknown if used.template => {
+                return Err(format!(
+                    "{} reverses a route whose name is a variable, so nothing here can tell \
+                     whether it is this one",
+                    position(db, used.file, used.range)
+                ));
+            }
+            Written::Unknown => {
+                return Err(format!(
+                    "{} reverses a route whose name is worked out at run time, so nothing here \
+                     can tell whether it is this one",
+                    position(db, used.file, used.range)
+                ));
+            }
+            Written::Stray => {
+                return Err(format!(
+                    "{} writes this route's name somewhere no rename would rewrite it",
+                    position(db, used.file, used.range)
+                ));
+            }
+            Written::Bound(bound_to) => {
+                if let Some(refusal) = bound_elsewhere(db, used, bound_to, &route.uses.found) {
+                    return Err(refusal);
+                }
+            }
+            Written::Itself => {}
+        }
+    }
+
+    sort(db, &mut edits);
+
+    Ok(Plan {
+        range: match anchor {
+            Anchor::Declaration { .. } => declared.range,
+            Anchor::Use { name } => tail(range, name, &bare)?,
+        },
+        placeholder: bare,
+        edits,
+        kind: Kind::Route,
+    })
+}
+
+/// the range of `used` a rename replaces
+///
+/// a use whose source text does not spell one of `names` outright is one written
+/// with an escape, and the arithmetic that finds a name inside a literal would
+/// then land in the wrong place.
+fn replaced(db: &dyn Db, used: &Use, names: &[&str], bare: &str) -> Result<TextRange, String> {
+    let source = source_text(db, used.file);
+    let written = &source[used.range];
+
+    if !names.contains(&written) {
+        return Err(
+            "a route name is written with an escape in it, so the name inside the literal cannot \
+             be located"
+                .to_string(),
+        );
+    }
+
+    tail(used.range, written, bare)
+}
+
+/// the part of the literal spanning `range` that writes the bare name
+///
+/// every use writes the name django reverses it by, which is qualified by the
+/// namespaces it is mounted under, while the declaration writes only the bare
+/// name — so a rename that reads the same at both ends replaces the tail.
+fn tail(range: TextRange, name: &str, bare: &str) -> Result<TextRange, String> {
+    if !fits(range, name) {
+        return Err(
+            "a route name is written with an escape in it, so the name inside the literal cannot \
+             be located"
+                .to_string(),
+        );
+    }
+
+    let bare = TextSize::try_from(bare.len()).map_err(|_| "the name is too long".to_string())?;
+    Ok(TextRange::new(range.end() - bare, range.end()))
+}
+
+/// whether a literal's contents are written exactly as its value reads
+///
+/// an escape makes the source longer than the value, and the arithmetic that
+/// finds a name inside the literal would then land in the wrong place.
+fn fits(range: TextRange, value: &str) -> bool {
+    usize::from(range.len()) == value.len()
+}
+
+// ---------------------------------------------------------------------------
+// a template name
+// ---------------------------------------------------------------------------
+
+fn template_plan(db: &dyn Db, name: &str, range: TextRange) -> Result<Plan, String> {
+    let loaded = uses::template(db, name);
+    if let Some(refusal) = loaded.uses.incomplete {
+        return Err(refusal);
+    }
+    let Some(discovered) = loaded.discovered else {
+        return Err(format!(
+            "no template of the project is loadable as `{name}`"
+        ));
+    };
+    let Some(root) = discovered.root() else {
+        return Err(format!(
+            "`{name}` is not below the template directory it was found under"
+        ));
+    };
+
+    let mut edits = Vec::new();
+
+    for used in &loaded.uses.found {
+        match &used.written {
+            Written::Whole if used.own => edits.push(FileRange::new(used.file, used.range)),
+            Written::Whole => {
+                return Err(format!(
+                    "{} loads this template, and an installed app's template is not the \
+                     project's to rewrite",
+                    position(db, used.file, used.range)
+                ));
+            }
+            Written::Pieces => {
+                return Err(format!(
+                    "{} names this template in two pieces, which no one range could replace",
+                    position(db, used.file, used.range)
+                ));
+            }
+            Written::Unknown if used.template => {
+                return Err(format!(
+                    "{} extends or includes a template whose name is a variable, so nothing here \
+                     can tell whether it is this one",
+                    position(db, used.file, used.range)
+                ));
+            }
+            Written::Unknown => {
+                return Err(format!(
+                    "{} renders a template whose name is worked out at run time, so nothing here \
+                     can tell whether it is this one",
+                    position(db, used.file, used.range)
+                ));
+            }
+            Written::Stray => {
+                return Err(format!(
+                    "{} writes this template's name somewhere no rename would rewrite it",
+                    position(db, used.file, used.range)
+                ));
+            }
+            Written::Bound(bound_to) => {
+                if let Some(refusal) = bound_elsewhere(db, used, bound_to, &loaded.uses.found) {
+                    return Err(refusal);
+                }
+            }
+            // the file the name loads is moved rather than edited
+            Written::Itself => {}
+        }
+    }
+
+    sort(db, &mut edits);
+
+    Ok(Plan {
+        range,
+        placeholder: name.to_compact_string(),
+        edits,
+        kind: Kind::Template {
+            path: discovered.path.clone(),
+            root: root.to_path_buf(),
+        },
+    })
+}
+
+// ---------------------------------------------------------------------------
+// settling on a new name
+// ---------------------------------------------------------------------------
+
+impl Plan {
+    fn finish(self, db: &dyn Db, new_name: &str) -> Result<TemplateRename, String> {
+        if new_name.is_empty() || new_name.chars().any(char::is_whitespace) {
+            return Err("a django name cannot be empty or hold a space".to_string());
+        }
+        if new_name.contains(['{', '}', '%', '"', '\'', '\\']) {
+            return Err(
+                "a django name cannot hold a quote, a backslash or a template delimiter"
+                    .to_string(),
+            );
+        }
+
+        let file_rename = match &self.kind {
+            // one template declaring a block twice is one django refuses to
+            // render, so a name already taken in a template this would edit is a
+            // rename that cannot be completed
+            Kind::Block { declaring } => {
+                if let Some(clash) = declaring
+                    .iter()
+                    .find(|member| uses::defines_block(db, **member, new_name))
+                {
+                    return Err(format!(
+                        "`{}` already declares a block named `{new_name}`, and django renders no \
+                         template that declares one twice",
+                        uses::path_of(db, *clash)
+                    ));
+                }
+                None
+            }
+            Kind::Route => {
+                if new_name.contains(NAMESPACE_SEPARATOR) {
+                    return Err(format!(
+                        "a route's own name holds no `{NAMESPACE_SEPARATOR}` — the namespaces in \
+                         front of it come from where its url configuration is included"
+                    ));
+                }
+                None
+            }
+            Kind::Template { path, root } => {
+                if new_name.contains(FRAGMENT_SEPARATOR) {
+                    return Err(format!(
+                        "a template's name holds no `{FRAGMENT_SEPARATOR}`, which addresses a \
+                         partial inside one"
+                    ));
+                }
+                if new_name.starts_with('/')
+                    || new_name.ends_with('/')
+                    || new_name
+                        .split('/')
+                        .any(|segment| segment.is_empty() || segment == "..")
+                {
+                    return Err(
+                        "a template's name is a path relative to its template directory"
+                            .to_string(),
+                    );
+                }
+                if project::template_files(db, db.project())
+                    .iter()
+                    .any(|discovered| discovered.name == new_name)
+                {
+                    return Err(format!("a template is already loadable as `{new_name}`"));
+                }
+
+                Some((path.clone(), root.join(new_name)))
+            }
+        };
+
+        Ok(TemplateRename {
+            edits: self.edits,
+            file_rename,
+        })
+    }
+}
+
+/// why the rename cannot go ahead, when a constant binds the name somewhere no
+/// other occurrence already covers
+///
+/// a constant carries the name somewhere this cannot follow — into a `render()`
+/// as a variable, into a helper, into a setting — so the rename stops at the
+/// binding and says which one. a `template_name = "…"` is a binding *and* a
+/// position the rename already rewrites, which is no reason to refuse.
+fn bound_elsewhere(db: &dyn Db, binding: &Use, bound_to: &str, found: &[Use]) -> Option<String> {
+    let rewritten = found.iter().any(|used| {
+        matches!(used.written, Written::Whole)
+            && used.file == binding.file
+            && binding.range.contains_range(used.range)
+    });
+
+    (!rewritten).then(|| {
+        format!(
+            "{} binds this name to `{bound_to}`, and a rename cannot follow where a constant \
+             carries it",
+            position(db, binding.file, binding.range)
+        )
+    })
+}
+
+/// how a refusal names the place it is refusing over
+fn position(db: &dyn Db, file: File, range: TextRange) -> String {
+    let line = source_text(db, file)[..usize::from(range.start())]
+        .matches('\n')
+        .count()
+        + 1;
+
+    format!("`{}:{line}`", uses::path_of(db, file))
+}
+
+/// put the edits in a stable order, so that two runs answer the same
+fn sort(db: &dyn Db, edits: &mut [FileRange]) {
+    edits.sort_by(|left, right| {
+        uses::path_of(db, left.file())
+            .cmp(&uses::path_of(db, right.file()))
+            .then(left.range().start().cmp(&right.range().start()))
+    });
+}
+
+#[cfg(test)]
+mod tests {
+    use crate::django_template::tests::TemplateTest;
+
+    /// a whole django project, with `sources` written into it
+    ///
+    /// the settings module the convention finds, and every app it names being
+    /// resolvable, is what makes the indexes authoritative — and every rename
+    /// here depends on that, since a rename that cannot see the whole project is
+    /// one that refuses.
+    fn project(sources: &[(&str, &str)]) -> TemplateTest {
+        let mut all: Vec<(&str, &str)> = vec![
+            (
+                "manage.py",
+                "
+                import os
+
+                os.environ.setdefault('DJANGO_SETTINGS_MODULE', 'project.settings')
+                ",
+            ),
+            ("project/__init__.py", ""),
+            (
+                "project/settings.py",
+                "
+                INSTALLED_APPS = ['blog']
+
+                TEMPLATES = [{'DIRS': [], 'APP_DIRS': True, 'OPTIONS': {}}]
+
+                ROOT_URLCONF = 'project.urls'
+                ",
+            ),
+            (
+                "project/urls.py",
+                "
+                from django.urls import include, path
+
+                urlpatterns = [path('blog/', include('blog.urls'))]
+                ",
+            ),
+            ("blog/__init__.py", ""),
+        ];
+        all.extend_from_slice(sources);
+
+        TemplateTest::with_site_packages(&all, &[])
+    }
+
+    /// the same project with a url configuration, a view and a base template
+    fn blog(sources: &[(&str, &str)]) -> TemplateTest {
+        let mut all: Vec<(&str, &str)> = vec![
+            (
+                "blog/urls.py",
+                "
+                from django.urls import path
+
+                app_name = 'blog'
+
+                urlpatterns = [
+                    path('', index, name='index'),
+                    path('<int:pk>/', detail, name='detail'),
+                ]
+                ",
+            ),
+            (
+                "blog/templates/blog/base.html",
+                "{% block content %}{% endblock content %}{% block footer %}{% endblock %}",
+            ),
+        ];
+        all.extend_from_slice(sources);
+
+        project(&all)
+    }
+
+    // -----------------------------------------------------------------------
+    // a `{% block %}` name
+    // -----------------------------------------------------------------------
+
+    #[test]
+    fn renaming_a_block_in_a_base_renames_every_child_that_overrides_it() {
+        let test = blog(&[
+            (
+                "blog/templates/blog/post.html",
+                "{% extends 'blog/base.html' %}{% block content %}a{% endblock %}",
+            ),
+            (
+                "blog/templates/blog/list.html",
+                "{% extends 'blog/base.html' %}{% block content %}b{% endblock content %}",
+            ),
+            (
+                "blog/templates/blog/edit.html",
+                "{% extends 'blog/base.html' %}{% block co<CURSOR>ntent %}c{% endblock %}",
+            ),
+        ]);
+
+        assert_eq!(
+            test.rename("body"),
+            [
+                "/src/blog/templates/blog/base.html:1 content -> body",
+                "/src/blog/templates/blog/base.html:1 content -> body",
+                "/src/blog/templates/blog/edit.html:1 content -> body",
+                "/src/blog/templates/blog/list.html:1 content -> body",
+                "/src/blog/templates/blog/list.html:1 content -> body",
+                "/src/blog/templates/blog/post.html:1 content -> body",
+            ]
+        );
+    }
+
+    #[test]
+    fn renaming_a_block_from_the_base_reaches_the_same_templates() {
+        let test = blog(&[
+            (
+                "blog/templates/blog/post.html",
+                "{% extends 'blog/base.html' %}{% block content %}a{% endblock %}",
+            ),
+            (
+                "blog/templates/blog/grandchild.html",
+                "{% extends 'blog/post.html' %}{% block content %}b{% endblock %}",
+            ),
+            (
+                "blog/templates/blog/unrelated.html",
+                "{% block content %}{% endblock %}",
+            ),
+            (
+                "blog/templates/blog/seed.html",
+                "{% extends 'blog/base.html' %}{% block cont<CURSOR>ent %}{% endblock %}",
+            ),
+        ]);
+
+        let renamed = test.rename("body");
+        assert!(
+            renamed.contains(
+                &"/src/blog/templates/blog/grandchild.html:1 content -> body".to_string()
+            ),
+            "got {renamed:?}"
+        );
+        assert!(
+            !renamed.iter().any(|edit| edit.contains("unrelated.html")),
+            "a template joined to no chain of this one's is not in the family: got {renamed:?}"
+        );
+    }
+
+    #[test]
+    fn a_named_closing_tag_is_renamed_with_the_block_it_closes() {
+        let test = blog(&[(
+            "blog/templates/blog/post.html",
+            "{% extends 'blog/base.html' %}{% block cont<CURSOR>ent %}a{% endblock content %}",
+        )]);
+
+        assert_eq!(
+            test.rename("body"),
+            [
+                "/src/blog/templates/blog/base.html:1 content -> body",
+                "/src/blog/templates/blog/base.html:1 content -> body",
+                "/src/blog/templates/blog/post.html:1 content -> body",
+                "/src/blog/templates/blog/post.html:1 content -> body",
+            ]
+        );
+    }
+
+    #[test]
+    fn a_block_rename_is_refused_when_a_template_picks_its_parent_at_render_time() {
+        let test = blog(&[
+            (
+                "blog/templates/blog/dynamic.html",
+                "{% extends parent %}{% block content %}a{% endblock %}",
+            ),
+            (
+                "blog/templates/blog/post.html",
+                "{% extends 'blog/base.html' %}{% block cont<CURSOR>ent %}b{% endblock %}",
+            ),
+        ]);
+
+        let refusal = test.prepare_rename();
+        assert!(
+            refusal.starts_with("refused:") && refusal.contains("dynamic.html"),
+            "got {refusal}"
+        );
+        assert_eq!(test.rename("body"), [refusal]);
+    }
+
+    #[test]
+    fn a_block_rename_is_refused_when_the_settings_cannot_be_read() {
+        // no settings module means no `INSTALLED_APPS`, and so no way to know
+        // that an installed app holds no template overriding this block
+        let test = TemplateTest::new(&[
+            (
+                "blog/templates/blog/base.html",
+                "{% block content %}{% endblock %}",
+            ),
+            (
+                "blog/templates/blog/post.html",
+                "{% extends 'blog/base.html' %}{% block cont<CURSOR>ent %}{% endblock %}",
+            ),
+        ]);
+
+        assert!(
+            test.prepare_rename().contains("settings could not be read"),
+            "got {}",
+            test.prepare_rename()
+        );
+    }
+
+    #[test]
+    fn a_block_rename_is_refused_when_the_new_name_is_already_declared() {
+        let test = blog(&[(
+            "blog/templates/blog/post.html",
+            "{% extends 'blog/base.html' %}{% block cont<CURSOR>ent %}{% endblock %}\
+             {% block footer %}{% endblock %}",
+        )]);
+
+        assert_eq!(
+            test.rename("footer"),
+            [
+                "refused: `/src/blog/templates/blog/post.html` already declares a block named \
+                 `footer`, and django renders no template that declares one twice"
+            ]
+        );
+    }
+
+    /// the same project with a `widgets` app installed beside it, holding
+    /// `installed`
+    ///
+    /// an installed app's templates are django's to load and nobody's to
+    /// rewrite, which is what makes them the interesting half of every scan.
+    fn with_installed_app(sources: &[(&str, &str)], installed: &[(&str, &str)]) -> TemplateTest {
+        let mut all: Vec<(&str, &str)> = vec![
+            (
+                "manage.py",
+                "
+                import os
+
+                os.environ.setdefault('DJANGO_SETTINGS_MODULE', 'project.settings')
+                ",
+            ),
+            ("project/__init__.py", ""),
+            (
+                "project/settings.py",
+                "
+                INSTALLED_APPS = ['blog', 'widgets']
+
+                TEMPLATES = [{'DIRS': [], 'APP_DIRS': True, 'OPTIONS': {}}]
+
+                ROOT_URLCONF = 'project.urls'
+                ",
+            ),
+            (
+                "project/urls.py",
+                "
+                from django.urls import include, path
+
+                urlpatterns = [path('blog/', include('blog.urls'))]
+                ",
+            ),
+            ("blog/__init__.py", ""),
+            (
+                "blog/urls.py",
+                "
+                from django.urls import path
+
+                app_name = 'blog'
+
+                urlpatterns = [path('<int:pk>/', detail, name='detail')]
+                ",
+            ),
+        ];
+        all.extend_from_slice(sources);
+
+        let mut packaged: Vec<(&str, &str)> = vec![("widgets/__init__.py", "")];
+        packaged.extend_from_slice(installed);
+
+        TemplateTest::with_site_packages(&all, &packaged)
+    }
+
+    #[test]
+    fn a_block_rename_is_refused_when_an_installed_app_overrides_it() {
+        let test = with_installed_app(
+            &[
+                (
+                    "blog/templates/blog/base.html",
+                    "{% block content %}{% endblock %}",
+                ),
+                (
+                    "blog/templates/blog/post.html",
+                    "{% extends 'blog/base.html' %}{% block cont<CURSOR>ent %}{% endblock %}",
+                ),
+            ],
+            &[(
+                "widgets/templates/widgets/panel.html",
+                "{% extends 'blog/base.html' %}{% block content %}x{% endblock %}",
+            )],
+        );
+
+        let refusal = test.prepare_rename();
+        assert!(
+            refusal.contains("panel.html") && refusal.contains("not the project's to rewrite"),
+            "got {refusal}"
+        );
+    }
+
+    #[test]
+    fn an_installed_apps_own_url_variable_does_not_refuse_a_route_rename() {
+        // a reusable app reverses its *own* routes at render time, and it is code
+        // this could not have rewritten whatever it said
+        let test = with_installed_app(
+            &[(
+                "blog/templates/blog/post.html",
+                "{% url 'blog:de<CURSOR>tail' %}",
+            )],
+            &[(
+                "widgets/templates/widgets/panel.html",
+                "{% url chosen %}{% url 'widgets:index' %}",
+            )],
+        );
+
+        assert_eq!(
+            test.rename("entry"),
+            [
+                "/src/blog/templates/blog/post.html:1 detail -> entry",
+                "/src/blog/urls.py:6 detail -> entry",
+            ]
+        );
+    }
+
+    #[test]
+    fn an_installed_apps_template_spelling_the_route_does_refuse_it() {
+        // this one is no speculation: the name is written out, and it is written
+        // somewhere a rename cannot reach
+        let test = with_installed_app(
+            &[(
+                "blog/templates/blog/post.html",
+                "{% url 'blog:de<CURSOR>tail' %}",
+            )],
+            &[(
+                "widgets/templates/widgets/panel.html",
+                "{% url 'blog:detail' %}",
+            )],
+        );
+
+        let refusal = test.prepare_rename();
+        assert!(
+            refusal.contains("panel.html") && refusal.contains("not the project's to rewrite"),
+            "got {refusal}"
+        );
+    }
+
+    #[test]
+    fn a_tag_name_is_not_a_block_name() {
+        let test = blog(&[(
+            "blog/templates/blog/post.html",
+            "{% bl<CURSOR>ock content %}{% endblock %}",
+        )]);
+
+        assert_eq!(test.prepare_rename(), "no rename");
+    }
+
+    // -----------------------------------------------------------------------
+    // a route name
+    // -----------------------------------------------------------------------
+
+    #[test]
+    fn renaming_a_route_from_a_template_reaches_the_declaration_and_the_python() {
+        let test = blog(&[
+            (
+                "blog/views.py",
+                "
+                from django.urls import reverse, reverse_lazy
+
+
+                def go(request):
+                    reverse('blog:detail')
+                    reverse_lazy('blog:detail')
+                    return redirect('blog:detail')
+                ",
+            ),
+            (
+                "blog/templates/blog/post.html",
+                "{% url 'blog:de<CURSOR>tail' pk=1 %}{% url 'blog:index' %}",
+            ),
+        ]);
+
+        assert_eq!(test.prepare_rename(), "rename `detail`, replacing `detail`");
+        assert_eq!(
+            test.rename("entry"),
+            [
+                "/src/blog/templates/blog/post.html:1 detail -> entry",
+                "/src/blog/urls.py:8 detail -> entry",
+                "/src/blog/views.py:6 detail -> entry",
+                "/src/blog/views.py:7 detail -> entry",
+                "/src/blog/views.py:8 detail -> entry",
+            ]
+        );
+    }
+
+    #[test]
+    fn renaming_a_route_from_its_declaration_keeps_the_namespace_on_every_use() {
+        let test = blog(&[
+            (
+                "blog/urls.py",
+                "
+                from django.urls import path
+
+                app_name = 'blog'
+
+                urlpatterns = [path('<int:pk>/', detail, name='de<CURSOR>tail')]
+                ",
+            ),
+            (
+                "blog/templates/blog/post.html",
+                "{% url 'blog:detail' pk=1 %}",
+            ),
+        ]);
+
+        assert_eq!(test.prepare_rename(), "rename `detail`, replacing `detail`");
+        assert_eq!(
+            test.rename("entry"),
+            [
+                "/src/blog/templates/blog/post.html:1 detail -> entry",
+                "/src/blog/urls.py:6 detail -> entry",
+            ]
+        );
+    }
+
+    #[test]
+    fn a_route_can_be_renamed_from_a_reverse_in_python() {
+        let test = blog(&[
+            (
+                "blog/templates/blog/post.html",
+                "{% url 'blog:detail' pk=1 %}",
+            ),
+            (
+                "blog/views.py",
+                "
+                from django.urls import reverse
+
+
+                def go(request):
+                    return reverse('blog:de<CURSOR>tail')
+                ",
+            ),
+        ]);
+
+        assert_eq!(test.prepare_rename(), "rename `detail`, replacing `detail`");
+        assert_eq!(
+            test.rename("entry"),
+            [
+                "/src/blog/templates/blog/post.html:1 detail -> entry",
+                "/src/blog/urls.py:8 detail -> entry",
+                "/src/blog/views.py:6 detail -> entry",
+            ]
+        );
+    }
+
+    #[test]
+    fn one_bare_name_under_two_namespaces_is_two_routes() {
+        let test = project(&[
+            (
+                "project/urls.py",
+                "
+                from django.urls import include, path
+
+                urlpatterns = [
+                    path('blog/', include('blog.urls')),
+                    path('shop/', include('shop.urls')),
+                ]
+                ",
+            ),
+            ("shop/__init__.py", ""),
+            (
+                "shop/urls.py",
+                "
+                from django.urls import path
+
+                app_name = 'shop'
+
+                urlpatterns = [path('<int:pk>/', detail, name='detail')]
+                ",
+            ),
+            (
+                "blog/urls.py",
+                "
+                from django.urls import path
+
+                app_name = 'blog'
+
+                urlpatterns = [path('<int:pk>/', detail, name='detail')]
+                ",
+            ),
+            (
+                "blog/templates/blog/post.html",
+                "{% url 'blog:de<CURSOR>tail' %}{% url 'shop:detail' %}",
+            ),
+        ]);
+
+        assert_eq!(
+            test.rename("entry"),
+            [
+                "/src/blog/templates/blog/post.html:1 detail -> entry",
+                "/src/blog/urls.py:6 detail -> entry",
+            ]
+        );
+    }
+
+    #[test]
+    fn a_route_rename_is_refused_for_a_name_a_router_generates() {
+        let test = project(&[
+            (
+                "project/urls.py",
+                "
+                from django.urls import include, path
+                from rest_framework.routers import DefaultRouter
+
+                from blog.views import BookViewSet
+
+                router = DefaultRouter()
+                router.register('books', BookViewSet, basename='book')
+
+                urlpatterns = [path('api/', include(router.urls))]
+                ",
+            ),
+            (
+                "blog/views.py",
+                "
+                class BookViewSet:
+                    pass
+                ",
+            ),
+            (
+                "blog/templates/blog/post.html",
+                "{% url 'book-<CURSOR>list' %}",
+            ),
+        ]);
+
+        assert!(
+            test.prepare_rename().contains("basename"),
+            "got {}",
+            test.prepare_rename()
+        );
+    }
+
+    #[test]
+    fn a_route_rename_is_refused_when_a_reverse_names_the_route_at_run_time() {
+        let test = blog(&[
+            (
+                "blog/views.py",
+                "
+                from django.urls import reverse
+
+
+                def go(request, wanted):
+                    return reverse(wanted)
+                ",
+            ),
+            (
+                "blog/templates/blog/post.html",
+                "{% url 'blog:de<CURSOR>tail' %}",
+            ),
+        ]);
+
+        let refusal = test.prepare_rename();
+        assert!(
+            refusal.contains("worked out at run time") && refusal.contains("views.py:6"),
+            "got {refusal}"
+        );
+    }
+
+    #[test]
+    fn a_route_rename_reaches_a_rest_framework_hyperlinked_field() {
+        let test = blog(&[
+            (
+                "blog/serializers.py",
+                "
+                class BookSerializer:
+                    url = HyperlinkedIdentityField(view_name='blog:detail')
+                ",
+            ),
+            (
+                "blog/templates/blog/post.html",
+                "{% url 'blog:de<CURSOR>tail' %}",
+            ),
+        ]);
+
+        assert_eq!(
+            test.rename("entry"),
+            [
+                "/src/blog/serializers.py:3 detail -> entry",
+                "/src/blog/templates/blog/post.html:1 detail -> entry",
+                "/src/blog/urls.py:8 detail -> entry",
+            ]
+        );
+    }
+
+    #[test]
+    fn a_literal_spelling_the_route_somewhere_unrelated_blocks_nothing() {
+        // `detail` is among the commonest strings in any codebase. a dict lookup
+        // in code that has nothing to do with django is not a use of the route,
+        // and refusing over one would make the commonest route names unrenameable
+        let test = blog(&[
+            (
+                "blog/report.py",
+                "
+                def summarise(item):
+                    seen = ['detail', 'index']
+                    return item.get('detail'), {'detail': 1}, summarise('detail')
+                ",
+            ),
+            (
+                "blog/templates/blog/post.html",
+                "{% url 'blog:de<CURSOR>tail' %}",
+            ),
+        ]);
+
+        assert_eq!(
+            test.rename("entry"),
+            [
+                "/src/blog/templates/blog/post.html:1 detail -> entry",
+                "/src/blog/urls.py:8 detail -> entry",
+            ]
+        );
+    }
+
+    #[test]
+    fn a_constant_holding_the_route_name_refuses_the_rename() {
+        // a constant carries the name into a `reverse()` this cannot see, so the
+        // rename stops at the binding and says which one
+        let test = blog(&[
+            (
+                "blog/links.py",
+                "
+                BOOK_ROUTE = 'blog:detail'
+
+
+                def link():
+                    return reverse(BOOK_ROUTE)
+                ",
+            ),
+            (
+                "blog/templates/blog/post.html",
+                "{% url 'blog:de<CURSOR>tail' %}",
+            ),
+        ]);
+
+        assert_eq!(
+            test.rename("entry"),
+            [
+                "refused: `/src/blog/links.py:2` binds this name to `BOOK_ROUTE`, and a rename \
+                 cannot follow where a constant carries it"
+            ]
+        );
+    }
+
+    #[test]
+    fn a_constant_in_a_class_body_refuses_it_too() {
+        let test = blog(&[
+            (
+                "blog/links.py",
+                "
+                class Links:
+                    BOOK_ROUTE = 'blog:detail'
+                ",
+            ),
+            (
+                "blog/templates/blog/post.html",
+                "{% url 'blog:de<CURSOR>tail' %}",
+            ),
+        ]);
+
+        assert!(
+            test.prepare_rename()
+                .contains("binds this name to `BOOK_ROUTE`"),
+            "got {}",
+            test.prepare_rename()
+        );
+    }
+
+    #[test]
+    fn a_name_bound_inside_a_function_blocks_nothing_on_its_own() {
+        // it is visible only in that body, so the only way out is a call this
+        // already reads — and reads as an argument it cannot follow, which
+        // refuses on its own
+        let test = blog(&[
+            (
+                "blog/report.py",
+                "
+                def summarise():
+                    wanted = 'blog:detail'
+                    return wanted
+                ",
+            ),
+            (
+                "blog/templates/blog/post.html",
+                "{% url 'blog:de<CURSOR>tail' %}",
+            ),
+        ]);
+
+        assert_eq!(
+            test.rename("entry"),
+            [
+                "/src/blog/templates/blog/post.html:1 detail -> entry",
+                "/src/blog/urls.py:8 detail -> entry",
+            ]
+        );
+    }
+
+    #[test]
+    fn a_route_rename_is_refused_when_a_template_reverses_a_variable() {
+        let test = blog(&[
+            ("blog/templates/blog/nav.html", "{% url target %}"),
+            (
+                "blog/templates/blog/post.html",
+                "{% url 'blog:de<CURSOR>tail' %}",
+            ),
+        ]);
+
+        let refusal = test.prepare_rename();
+        assert!(refusal.contains("nav.html:1"), "got {refusal}");
+    }
+
+    #[test]
+    fn a_route_cannot_be_renamed_to_a_qualified_name() {
+        let test = blog(&[(
+            "blog/templates/blog/post.html",
+            "{% url 'blog:de<CURSOR>tail' %}",
+        )]);
+
+        assert_eq!(
+            test.rename("shop:detail"),
+            [
+                "refused: a route's own name holds no `:` — the namespaces in front of it come \
+                 from where its url configuration is included"
+            ]
+        );
+    }
+
+    #[test]
+    fn a_route_rename_is_refused_when_the_url_tree_cannot_be_read() {
+        // no settings module means no `ROOT_URLCONF`, and so no way to know which
+        // namespace a name is reversed under
+        let test = TemplateTest::new(&[
+            (
+                "blog/urls.py",
+                "urlpatterns = [path('', detail, name='detail')]",
+            ),
+            (
+                "blog/templates/blog/post.html",
+                "{% url 'de<CURSOR>tail' %}",
+            ),
+        ]);
+
+        assert!(
+            test.prepare_rename().contains("url configuration"),
+            "got {}",
+            test.prepare_rename()
+        );
+    }
+
+    // -----------------------------------------------------------------------
+    // a template name
+    // -----------------------------------------------------------------------
+
+    #[test]
+    fn renaming_a_template_rewrites_every_reference_and_moves_the_file() {
+        let test = blog(&[
+            (
+                "blog/views.py",
+                "
+                from django.shortcuts import render
+
+
+                def post(request):
+                    return render(request, 'blog/post.html', {})
+
+
+                class PostView:
+                    template_name = 'blog/post.html'
+                ",
+            ),
+            (
+                "blog/templates/blog/list.html",
+                "{% include 'blog/post.html' %}{% include 'blog/post.html#card' %}",
+            ),
+            (
+                "blog/templates/blog/child.html",
+                "{% extends 'blog/p<CURSOR>ost.html' %}",
+            ),
+            (
+                "blog/templates/blog/post.html",
+                "{% extends 'blog/base.html' %}{% partialdef card %}x{% endpartialdef %}",
+            ),
+        ]);
+
+        assert_eq!(
+            test.prepare_rename(),
+            "rename `blog/post.html`, replacing `blog/post.html`"
+        );
+        assert_eq!(
+            test.rename("blog/entry.html"),
+            [
+                "/src/blog/templates/blog/child.html:1 blog/post.html -> blog/entry.html",
+                "/src/blog/templates/blog/list.html:1 blog/post.html -> blog/entry.html",
+                "/src/blog/templates/blog/list.html:1 blog/post.html -> blog/entry.html",
+                "/src/blog/views.py:6 blog/post.html -> blog/entry.html",
+                "/src/blog/views.py:10 blog/post.html -> blog/entry.html",
+                "move /src/blog/templates/blog/post.html -> /src/blog/templates/blog/entry.html",
+            ]
+        );
+    }
+
+    #[test]
+    fn a_template_can_be_renamed_from_a_render_in_python() {
+        let test = blog(&[
+            (
+                "blog/views.py",
+                "
+                from django.shortcuts import render
+
+
+                def post(request):
+                    return render(request, 'blog/p<CURSOR>ost.html', {})
+                ",
+            ),
+            (
+                "blog/templates/blog/list.html",
+                "{% include 'blog/post.html' %}",
+            ),
+            ("blog/templates/blog/post.html", "x"),
+        ]);
+
+        assert_eq!(
+            test.rename("blog/entry.html"),
+            [
+                "/src/blog/templates/blog/list.html:1 blog/post.html -> blog/entry.html",
+                "/src/blog/views.py:6 blog/post.html -> blog/entry.html",
+                "move /src/blog/templates/blog/post.html -> /src/blog/templates/blog/entry.html",
+            ]
+        );
+    }
+
+    #[test]
+    fn a_template_rename_leaves_the_partial_a_reference_addresses_alone() {
+        let test = blog(&[
+            (
+                "blog/templates/blog/list.html",
+                "{% include 'blog/po<CURSOR>st.html#card' %}",
+            ),
+            (
+                "blog/templates/blog/post.html",
+                "{% partialdef card %}x{% endpartialdef %}",
+            ),
+        ]);
+
+        assert_eq!(
+            test.prepare_rename(),
+            "rename `blog/post.html`, replacing `blog/post.html`"
+        );
+    }
+
+    #[test]
+    fn a_template_rename_is_refused_when_a_render_names_its_template_at_run_time() {
+        let test = blog(&[
+            (
+                "blog/views.py",
+                "
+                from django.shortcuts import render
+
+
+                def post(request, chosen):
+                    return render(request, chosen, {})
+                ",
+            ),
+            (
+                "blog/templates/blog/child.html",
+                "{% extends 'blog/p<CURSOR>ost.html' %}",
+            ),
+            ("blog/templates/blog/post.html", "x"),
+        ]);
+
+        let refusal = test.prepare_rename();
+        assert!(
+            refusal.contains("worked out at run time") && refusal.contains("views.py:6"),
+            "got {refusal}"
+        );
+    }
+
+    #[test]
+    fn a_constant_holding_the_template_name_refuses_the_rename() {
+        let test = blog(&[
+            (
+                "blog/tasks.py",
+                "
+                WELCOME = 'blog/post.html'
+
+
+                def send(request):
+                    return render(request, WELCOME, {})
+                ",
+            ),
+            (
+                "blog/templates/blog/child.html",
+                "{% extends 'blog/p<CURSOR>ost.html' %}",
+            ),
+            ("blog/templates/blog/post.html", "x"),
+        ]);
+
+        assert_eq!(
+            test.rename("blog/entry.html"),
+            [
+                "refused: `/src/blog/tasks.py:2` binds this name to `WELCOME`, and a rename \
+                 cannot follow where a constant carries it"
+            ]
+        );
+    }
+
+    #[test]
+    fn the_template_name_of_a_view_class_is_rewritten_rather_than_refused() {
+        // it is a class-level binding *and* a position the rename already
+        // rewrites, so it is no reason to refuse
+        let test = blog(&[
+            (
+                "blog/views.py",
+                "
+                class PostView:
+                    template_name = 'blog/post.html'
+                ",
+            ),
+            (
+                "blog/templates/blog/child.html",
+                "{% extends 'blog/p<CURSOR>ost.html' %}",
+            ),
+            ("blog/templates/blog/post.html", "x"),
+        ]);
+
+        assert_eq!(
+            test.rename("blog/entry.html"),
+            [
+                "/src/blog/templates/blog/child.html:1 blog/post.html -> blog/entry.html",
+                "/src/blog/views.py:3 blog/post.html -> blog/entry.html",
+                "move /src/blog/templates/blog/post.html -> /src/blog/templates/blog/entry.html",
+            ]
+        );
+    }
+
+    #[test]
+    fn a_template_rename_is_refused_when_two_directories_hold_the_name() {
+        let test = blog(&[
+            ("blog/templates/blog/post.html", "x"),
+            ("shop/templates/blog/post.html", "y"),
+            (
+                "blog/templates/blog/child.html",
+                "{% extends 'blog/p<CURSOR>ost.html' %}",
+            ),
+        ]);
+
+        assert!(
+            test.prepare_rename()
+                .contains("two of the project's template directories"),
+            "got {}",
+            test.prepare_rename()
+        );
+    }
+
+    #[test]
+    fn a_template_cannot_be_renamed_over_one_that_is_already_there() {
+        let test = blog(&[
+            ("blog/templates/blog/post.html", "x"),
+            (
+                "blog/templates/blog/child.html",
+                "{% extends 'blog/p<CURSOR>ost.html' %}",
+            ),
+        ]);
+
+        assert_eq!(
+            test.rename("blog/base.html"),
+            ["refused: a template is already loadable as `blog/base.html`"]
+        );
+    }
+
+    #[test]
+    fn a_template_name_is_a_path_below_its_template_directory() {
+        let test = blog(&[
+            ("blog/templates/blog/post.html", "x"),
+            (
+                "blog/templates/blog/child.html",
+                "{% extends 'blog/p<CURSOR>ost.html' %}",
+            ),
+        ]);
+
+        assert_eq!(
+            test.rename("../escape.html"),
+            ["refused: a template's name is a path relative to its template directory"]
+        );
+    }
+}
diff --git a/crates/ty_ide/src/django_template/resolve.rs b/crates/ty_ide/src/django_template/resolve.rs
index 0cf06d4f57..12de421671 100644
--- a/crates/ty_ide/src/django_template/resolve.rs
+++ b/crates/ty_ide/src/django_template/resolve.rs
@@ -59,13 +59,25 @@ pub(crate) fn resolve_root<'a>(
         .map(Origin::Context)
 }
 
-/// every name the project's views put in this template's context
+/// every name in scope in this template, nearest first
+///
+/// a view's own context comes first, and the names the project's context
+/// processors put in every template's context follow it: a view supplying a name
+/// a processor also supplies is the one django renders with, exactly as a tag's
+/// binding outranks them both.
 pub(crate) fn context_variables(db: &dyn Db, template: File) -> Vec<&ContextVariable> {
-    let Some(name) = template_name(db, template) else {
-        return Vec::new();
+    let mut found = match template_name(db, template) {
+        Some(name) => project::context_for_template(db, &name),
+        None => Vec::new(),
     };
 
-    project::context_for_template(db, &name)
+    for variable in project::context_processor_variables(db, db.project()) {
+        if !found.iter().any(|existing| existing.name == variable.name) {
+            found.push(variable);
+        }
+    }
+
+    found
 }
 
 /// the name the template loader knows `file` by, e.g. `blog/post.html`
@@ -195,11 +207,23 @@ pub(crate) fn path_segments<'src>(
 ///
 /// [resolved]: https://docs.djangoproject.com/en/stable/ref/templates/language/#variables
 pub(crate) fn member_type<'db>(db: &'db dyn Db, ty: Type<'db>, name: &str) -> Option<Type<'db>> {
-    let member = members(db, ty)
-        .into_iter()
-        .find(|member| member.name == name)?;
+    Some(resolved(db, uncalled_member_type(db, ty, name)?))
+}
 
-    Some(resolved(db, member.ty))
+/// the type of `name` accessed on `ty`, before the template engine calls it
+///
+/// this is the difference between a method django *would* call and what it gives
+/// once it has: a diagnostic about a member django cannot call has to see the
+/// member itself.
+pub(crate) fn uncalled_member_type<'db>(
+    db: &'db dyn Db,
+    ty: Type<'db>,
+    name: &str,
+) -> Option<Type<'db>> {
+    members(db, ty)
+        .into_iter()
+        .find(|member| member.name == name)
+        .map(|member| member.ty)
 }
 
 /// what the template engine ends up with once it has resolved a lookup
diff --git a/crates/ty_ide/src/django_template/uses.rs b/crates/ty_ide/src/django_template/uses.rs
new file mode 100644
index 0000000000..1483ff7808
--- /dev/null
+++ b/crates/ty_ide/src/django_template/uses.rs
@@ -0,0 +1,964 @@
+//! every place the project writes a django name
+//!
+//! two features ask this question and want opposite things from the answer. a
+//! rename must rewrite every occurrence or none of them: one left behind is a
+//! project that no longer renders, and nothing about the result looks wrong.
+//! references only has to *say* where the name is written, and an occurrence
+//! nothing could rewrite is still one worth knowing about.
+//!
+//! so the scans live here once, and every occurrence carries what it is — the
+//! name written out or worked out at run time, the project's own file or an
+//! installed app's, a position a rewrite knows or one it does not. the two
+//! features read that differently, and deliberately: [`Written`] is where the
+//! difference is written down, and a later reader tempted to make one of them
+//! agree with the other should read it first.
+//!
+//! what counts as evidence of a name at all is the one thing this is careful not
+//! to overdo. it is a position — one of the calls and attributes [`super::python`]
+//! reads, a template construct, or a constant a name is bound to, since a
+//! constant carries a name somewhere nothing here can follow. it is deliberately
+//! not "any literal spelling the same text": `detail`, `content` and `index` are
+//! among the commonest strings in any codebase, and an `item.get("detail")` in
+//! unrelated code is nothing to do with a route.
+
+use compact_str::{CompactString, ToCompactString};
+use ruff_db::files::{File, system_path_to_file};
+use ruff_db::parsed::parsed_module;
+use ruff_db::source::{SourceText, source_text};
+use ruff_python_ast::AnyNodeRef;
+use ruff_python_ast::find_node::covering_node;
+use ruff_text_size::{TextRange, TextSize};
+use rustc_hash::{FxHashMap, FxHashSet};
+use ty_project::Db;
+
+use super::index::{Definition, TemplateIndex};
+use super::lexer::{Construct, ConstructKind, Token, TokenKind, string_contents};
+use super::project::{self, DiscoveredFile, RegistrationKind};
+use super::{MAX_INHERITANCE_DEPTH, template_index};
+
+/// the tag that reverses a route
+pub(super) const URL_TAG: &str = "url";
+
+/// the tags that name another template
+pub(super) const TEMPLATE_TAGS: &[&str] = &["extends", "include"];
+
+/// the tag that closes a `{% block %}`
+const END_BLOCK_TAG: &str = "endblock";
+
+/// the fragment separator a template reference addresses a partial with
+pub(super) const FRAGMENT_SEPARATOR: char = '#';
+
+/// which django name a position writes
+pub(super) enum Named {
+    /// a `{% block %}` name
+    Block(CompactString),
+    /// a route, under the name it is reversed by
+    Route(CompactString),
+    /// a route's own `name=`
+    RouteDeclaration,
+    /// a template, under the name its loader knows it by
+    Template(CompactString),
+    /// a tag's name, as a template writes it
+    Tag(CompactString),
+    /// a filter's name, as a template writes it
+    Filter(CompactString),
+}
+
+/// one place a django name reaches
+pub(super) struct Use {
+    pub(super) file: File,
+    /// the range that writes the name, or the expression standing in for one
+    pub(super) range: TextRange,
+    pub(super) written: Written,
+    /// whether the file is the project's own, and so one a rename could edit
+    ///
+    /// an installed app's template is django's to load and nobody's to rewrite.
+    pub(super) own: bool,
+    /// whether it is a template that writes it, rather than python
+    pub(super) template: bool,
+    /// whether the occurrence declares the name rather than using it
+    pub(super) declaration: bool,
+}
+
+/// how a position writes the name
+///
+/// this is the whole of what the two callers disagree about. everything but
+/// [`Written::Unknown`] spells the name out, and so is a reference; everything
+/// but [`Written::Whole`] is somewhere a rename cannot simply replace, and so is
+/// a refusal. the overlap in the middle — a name written where no rewrite could
+/// reach it — is reported by one and refused by the other on purpose.
+pub(super) enum Written {
+    /// as one literal a single range covers
+    Whole,
+    /// as a literal written in more than one piece, which no one range covers
+    Pieces,
+    /// not at all: the position works the name out at run time, so this is only
+    /// *maybe* an occurrence of this name and no occurrence of it to report
+    Unknown,
+    /// as a literal somewhere nothing here reads as naming this kind of thing
+    Stray,
+    /// as the value of a constant, which carries the name out of sight
+    Bound(CompactString),
+    /// not as a name at all: the thing the name refers to, which is a position
+    /// to navigate to rather than one to rewrite
+    Itself,
+}
+
+/// where a django name is written, and how completely that could be worked out
+#[derive(Default)]
+pub(super) struct Uses {
+    pub(super) found: Vec<Use>,
+    /// why what was found may not be all of it
+    ///
+    /// a rename refuses over this; references ignores it, since an answer that
+    /// may be missing something is still worth giving while a rewrite that may
+    /// be missing something is not one to apply.
+    pub(super) incomplete: Option<String>,
+}
+
+/// what the position at `offset` of `file` writes
+///
+/// `template` says the file is a django template rather than python, which the
+/// caller knows and this cannot.
+pub(super) fn named_at(
+    db: &dyn Db,
+    file: File,
+    offset: TextSize,
+    template: bool,
+) -> Option<(Named, TextRange)> {
+    if template {
+        let source = source_text(db, file);
+        at_template(template_index(db, file), source.as_str(), offset)
+    } else {
+        at_python(db, file, offset)
+    }
+}
+
+/// what the position writes, read as a django template
+fn at_template(
+    index: &TemplateIndex,
+    source: &str,
+    offset: TextSize,
+) -> Option<(Named, TextRange)> {
+    let construct = index.lexed().construct_at(offset)?;
+    if construct.kind == ConstructKind::Comment {
+        return None;
+    }
+
+    let token = *index
+        .lexed()
+        .construct_tokens(construct)
+        .iter()
+        .find(|token| token.range.contains_inclusive(offset))?;
+
+    // a tag and a filter are named by their own token, wherever they are written
+    match token.kind {
+        TokenKind::TagName => {
+            return Some((
+                Named::Tag(source[token.range].to_compact_string()),
+                token.range,
+            ));
+        }
+        TokenKind::FilterName => {
+            return Some((
+                Named::Filter(source[token.range].to_compact_string()),
+                token.range,
+            ));
+        }
+        _ => {}
+    }
+
+    if construct.kind != ConstructKind::Tag {
+        return None;
+    }
+    let tag = &source[construct.name?];
+    let arguments = arguments(index, construct);
+    if !arguments
+        .iter()
+        .any(|argument| argument.range == token.range)
+    {
+        return None;
+    }
+
+    match tag {
+        "block" | END_BLOCK_TAG => {
+            let name = arguments.iter().find(|candidate| {
+                matches!(candidate.kind, TokenKind::Variable | TokenKind::String)
+            })?;
+            if name.range != token.range {
+                return None;
+            }
+
+            let range = string_contents(source, token.range);
+            Some((Named::Block(source[range].to_compact_string()), range))
+        }
+        URL_TAG => {
+            let range = first_string(source, arguments, token)?;
+            Some((Named::Route(source[range].to_compact_string()), range))
+        }
+        tag if TEMPLATE_TAGS.contains(&tag) => {
+            let range = strip_fragment(source, first_string(source, arguments, token)?);
+            Some((Named::Template(source[range].to_compact_string()), range))
+        }
+        _ => None,
+    }
+}
+
+/// the contents of the tag's first string argument, when `token` is that argument
+fn first_string(source: &str, arguments: &[Token], token: Token) -> Option<TextRange> {
+    let first = arguments
+        .iter()
+        .find(|candidate| candidate.kind == TokenKind::String)?;
+    if first.range != token.range {
+        return None;
+    }
+
+    let range = string_contents(source, token.range);
+    // a token that is not actually quoted names nothing that could be rewritten
+    (range != token.range).then_some(range)
+}
+
+/// `range` up to its `#`, which addresses a partial rather than naming the template
+fn strip_fragment(source: &str, range: TextRange) -> TextRange {
+    match source[range].find(FRAGMENT_SEPARATOR) {
+        Some(index) => TextRange::at(
+            range.start(),
+            TextSize::try_from(index).unwrap_or(range.len()),
+        ),
+        None => range,
+    }
+}
+
+/// a construct's tokens with its delimiters and its tag name dropped
+fn arguments<'a>(index: &'a TemplateIndex, construct: &Construct) -> &'a [Token] {
+    let tokens = index.lexed().inner_tokens(construct);
+
+    match tokens.split_first() {
+        Some((first, rest)) if first.kind == TokenKind::TagName => rest,
+        _ => tokens,
+    }
+}
+
+/// what the position writes, read as python
+fn at_python(db: &dyn Db, file: File, offset: TextSize) -> Option<(Named, TextRange)> {
+    // a route's own declaration is the `name=` the url index already recorded, so
+    // recognising one needs no reading of the call it sits in
+    if let Some(url) = project::url_names(db, db.project())
+        .iter()
+        .find(|url| url.file == file && url.range.contains_inclusive(offset))
+    {
+        return Some((Named::RouteDeclaration, url.range));
+    }
+
+    let parsed = parsed_module(db, file).load(db);
+    let (names, value, range) = super::python::name_at(&parsed, offset)?;
+
+    Some(match names {
+        super::python::Names::Template => (Named::Template(value), range),
+        super::python::Names::Route => (Named::Route(value), range),
+    })
+}
+
+// ---------------------------------------------------------------------------
+// a `{% block %}` name
+// ---------------------------------------------------------------------------
+
+/// every template of `file`'s inheritance family that declares the block `name`
+pub(super) fn block(db: &dyn Db, file: File, name: &str) -> Uses {
+    let mut incomplete = None;
+
+    if !project::settings_are_authoritative(db, db.project()) {
+        incomplete = Some(
+            "the project's settings could not be read in full, so the templates that override \
+             this block cannot all be found"
+                .to_string(),
+        );
+    }
+
+    let tree = Inheritance::of(db);
+
+    // a template whose ancestry has a gap in it may be overriding this very block
+    // somewhere nothing here would think to look
+    if incomplete.is_none()
+        && let Some(uncertain) = tree
+            .uncertain
+            .iter()
+            .find(|candidate| defines_block(db, **candidate, name))
+    {
+        incomplete = Some(format!(
+            "`{}` overrides `{name}`, and what it extends is decided at render time, so the \
+             templates that override this block cannot all be found",
+            path_of(db, *uncertain)
+        ));
+    }
+
+    let mut found = Vec::new();
+    for member in tree.family(file) {
+        if !defines_block(db, member, name) {
+            continue;
+        }
+
+        // the block is declared where nothing above it declares it, and overridden
+        // everywhere below
+        let declaration = !tree
+            .ancestors(member)
+            .any(|ancestor| defines_block(db, ancestor, name));
+
+        found.extend(block_names(db, member, name).into_iter().map(|range| Use {
+            file: member,
+            range,
+            written: Written::Whole,
+            own: !tree.foreign.contains(&member),
+            template: true,
+            declaration,
+        }));
+    }
+    sort(db, &mut found);
+
+    Uses { found, incomplete }
+}
+
+/// every template django can load, and the one it extends
+///
+/// the templates are kept in discovery order rather than only in the maps, so
+/// that the walks below answer the same way twice.
+struct Inheritance {
+    parents: FxHashMap<File, Option<File>>,
+    children: FxHashMap<File, Vec<File>>,
+    /// the templates whose chain of parents does not reach a root
+    uncertain: FxHashSet<File>,
+    /// the templates an installed app holds, which are nobody's to rewrite
+    foreign: FxHashSet<File>,
+}
+
+impl Inheritance {
+    fn of(db: &dyn Db) -> Self {
+        let mut order = Vec::new();
+        let mut parents: FxHashMap<File, Option<File>> = FxHashMap::default();
+        let mut children: FxHashMap<File, Vec<File>> = FxHashMap::default();
+        let mut broken: FxHashSet<File> = FxHashSet::default();
+        let mut foreign: FxHashSet<File> = FxHashSet::default();
+
+        for template in templates(db) {
+            let file = template.file;
+            if !template.own {
+                foreign.insert(file);
+            }
+
+            let parent = template
+                .index
+                .extends()
+                .and_then(|reference| project::resolve_template(db, &reference.name));
+
+            // an `{% extends %}` written as a variable, and one naming a template
+            // that isn't there, both leave this template's place in the tree unknown
+            if template.index.extends_unresolved()
+                || (template.index.extends().is_some() && parent.is_none())
+            {
+                broken.insert(file);
+            }
+
+            if let Some(parent) = parent {
+                children.entry(parent).or_default().push(file);
+            }
+            order.push(file);
+            parents.insert(file, parent);
+        }
+
+        let uncertain = order
+            .into_iter()
+            .filter(|file| {
+                let mut current = *file;
+                let mut seen = FxHashSet::default();
+
+                for _ in 0..MAX_INHERITANCE_DEPTH {
+                    // a chain that comes back round never reaches a root, and one
+                    // whose next link is not a template django could load has left
+                    // whatever this can see
+                    if broken.contains(&current) || !seen.insert(current) {
+                        return true;
+                    }
+                    match parents.get(&current) {
+                        Some(Some(parent)) => current = *parent,
+                        Some(None) => return false,
+                        None => return true,
+                    }
+                }
+
+                true
+            })
+            .collect();
+
+        Self {
+            parents,
+            children,
+            uncertain,
+            foreign,
+        }
+    }
+
+    /// every template joined to `file` by inheritance, however far along the chain
+    ///
+    /// a block is one name across the whole family: renaming it in a child means
+    /// renaming it in the parent it overrides, and so in every *other* child that
+    /// overrides the same parent.
+    fn family(&self, file: File) -> Vec<File> {
+        let mut queue = vec![file];
+        let mut seen: FxHashSet<File> = queue.iter().copied().collect();
+        let mut found = Vec::new();
+
+        while let Some(current) = queue.pop() {
+            found.push(current);
+
+            let upwards = self.parents.get(&current).copied().flatten();
+            let downwards = self.children.get(&current).into_iter().flatten().copied();
+
+            for neighbour in upwards.into_iter().chain(downwards) {
+                if seen.insert(neighbour) {
+                    queue.push(neighbour);
+                }
+            }
+        }
+
+        found
+    }
+
+    /// the templates `file` extends, nearest first
+    fn ancestors(&self, file: File) -> impl Iterator<Item = File> {
+        let mut current = Some(file);
+
+        std::iter::from_fn(move || {
+            let parent = self.parents.get(&current?).copied().flatten()?;
+            current = Some(parent);
+            Some(parent)
+        })
+        .take(MAX_INHERITANCE_DEPTH)
+    }
+}
+
+pub(super) fn defines_block(db: &dyn Db, file: File, name: &str) -> bool {
+    template_index(db, file)
+        .blocks()
+        .iter()
+        .any(|block| block.name == name)
+}
+
+/// every range of `file` that writes the block name `name`
+fn block_names(db: &dyn Db, file: File, name: &str) -> Vec<TextRange> {
+    let index = template_index(db, file);
+    let source = source_text(db, file);
+    let mut found = Vec::new();
+
+    for definition in index.blocks().iter().filter(|block| block.name == name) {
+        found.push(definition.name_range);
+
+        // `{% endblock content %}` writes the name a second time
+        if let Some(range) = closing_name(index, source.as_str(), definition) {
+            found.push(range);
+        }
+    }
+
+    found
+}
+
+/// the name written on the `{% endblock %}` that closes `definition`
+fn closing_name(index: &TemplateIndex, source: &str, definition: &Definition) -> Option<TextRange> {
+    let construct = index.lexed().constructs().iter().find(|construct| {
+        construct.kind == ConstructKind::Tag
+            && construct.range.end() == definition.full_range.end()
+            && construct.range.start() > definition.full_range.start()
+            && construct
+                .name
+                .is_some_and(|range| &source[range] == END_BLOCK_TAG)
+    })?;
+
+    let argument = arguments(index, construct)
+        .iter()
+        .find(|token| matches!(token.kind, TokenKind::Variable | TokenKind::String))?;
+
+    let range = string_contents(source, argument.range);
+    (source[range] == *definition.name.as_str()).then_some(range)
+}
+
+// ---------------------------------------------------------------------------
+// a route name
+// ---------------------------------------------------------------------------
+
+/// where the route being asked about is declared, and how the request reached it
+pub(super) enum Anchor {
+    /// the cursor is in the declaration's own `name=`, whose literal spans `range`
+    Declaration { file: File, range: TextRange },
+    /// the cursor is in a `{% url %}` or a `reverse()`, which writes `name`
+    Use { name: CompactString },
+}
+
+/// a route's own `name=`
+pub(super) struct Declared {
+    /// the literal's contents, or the whole literal where it is written in pieces
+    pub(super) range: TextRange,
+    /// the bare name it writes, absent where it is written in more than one piece
+    pub(super) name: Option<CompactString>,
+    /// whether every name it is reversed by is written out at `range`
+    ///
+    /// a rest framework router generates its routes' names from a basename rather
+    /// than writing them out, so what is written there is a piece of each of them.
+    pub(super) exact: bool,
+}
+
+/// a route, under every name it is reversed by
+pub(super) struct Route {
+    /// every name the route is reversed by, the namespaces it is mounted under
+    /// included
+    pub(super) names: Vec<CompactString>,
+    /// the one declaration the request identifies, where it identifies one
+    pub(super) declared: Option<Declared>,
+    pub(super) uses: Uses,
+}
+
+/// every place the route `anchor` identifies is reversed
+pub(super) fn route(db: &dyn Db, anchor: &Anchor) -> Route {
+    let project = db.project();
+    let mut incomplete = None;
+
+    if !project::routes_are_authoritative(db, project) {
+        incomplete = Some(
+            "the project's url configuration could not be read in full, so every place this \
+             route is reversed cannot be found"
+                .to_string(),
+        );
+    }
+    let urls = project::url_names(db, project);
+
+    // whichever end the request came from, the declaration is what identifies the
+    // route: two namespaces may give one bare name and one declaration may be
+    // mounted under two
+    let mut declarations: Vec<(File, TextRange)> = match anchor {
+        Anchor::Declaration { file, range } => vec![(*file, *range)],
+        Anchor::Use { name } => urls
+            .iter()
+            .filter(|url| url.name == *name)
+            .map(|url| (url.file, url.range))
+            .collect(),
+    };
+    declarations.sort_by_key(|(file, range)| (path_of(db, *file), range.start()));
+    declarations.dedup();
+
+    let one = match (declarations.as_slice(), anchor) {
+        ([only], _) => Some(*only),
+        ([], Anchor::Use { name }) => {
+            incomplete.get_or_insert_with(|| format!("no route of the project is named `{name}`"));
+            None
+        }
+        (_, Anchor::Use { name }) => {
+            incomplete.get_or_insert_with(|| {
+                format!(
+                    "`{name}` is given by more than one declaration, so renaming it would be \
+                     renaming several routes at once"
+                )
+            });
+            None
+        }
+        _ => None,
+    };
+
+    // the name a use writes is the one the declaration gives qualified by the
+    // namespaces it is mounted under, and one declaration may be mounted twice
+    let mut names: Vec<CompactString> = match (one, anchor) {
+        (Some(declaration), _) => urls
+            .iter()
+            .filter(|url| (url.file, url.range) == declaration)
+            .map(|url| url.name.clone())
+            .collect(),
+        (None, Anchor::Use { name }) => vec![name.clone()],
+        (None, Anchor::Declaration { .. }) => Vec::new(),
+    };
+    names.sort_unstable();
+    names.dedup();
+
+    let declared = one.map(|declaration| {
+        let (file, range) = declaration;
+        let exact = urls
+            .iter()
+            .filter(|url| (url.file, url.range) == declaration)
+            .all(|url| url.exact);
+
+        match python_literal(db, file, range) {
+            Some((name, contents)) => Declared {
+                range: contents,
+                name: Some(name),
+                exact,
+            },
+            None => Declared {
+                range,
+                name: None,
+                exact,
+            },
+        }
+    });
+
+    let mut found: Vec<Use> = declarations
+        .iter()
+        .map(|(file, range)| {
+            let (range, written) = match python_literal(db, *file, *range) {
+                Some((_, contents)) => (contents, Written::Whole),
+                None => (*range, Written::Pieces),
+            };
+
+            Use {
+                file: *file,
+                range,
+                written,
+                own: true,
+                template: false,
+                declaration: true,
+            }
+        })
+        .collect();
+
+    let listed: Vec<&str> = names.iter().map(CompactString::as_str).collect();
+    found.extend(bindings(db, &listed));
+    found.extend(python_uses(project::route_uses(db, project), &listed));
+    found.extend(template_uses(db, &[URL_TAG], &listed, false));
+
+    Route {
+        names,
+        declared,
+        uses: Uses { found, incomplete },
+    }
+}
+
+// ---------------------------------------------------------------------------
+// a template name
+// ---------------------------------------------------------------------------
+
+/// a template, and every place it is loaded
+pub(super) struct Loaded<'db> {
+    /// the file the name loads, where exactly one of the project's is loadable
+    /// as it
+    pub(super) discovered: Option<&'db DiscoveredFile>,
+    pub(super) uses: Uses,
+}
+
+/// every place the template `name` is extended, included or rendered
+pub(super) fn template<'db>(db: &'db dyn Db, name: &str) -> Loaded<'db> {
+    let project = db.project();
+    let mut incomplete = None;
+
+    if !project::settings_are_authoritative(db, project) {
+        incomplete = Some(
+            "the project's settings could not be read in full, so every place this template is \
+             loaded cannot be found"
+                .to_string(),
+        );
+    }
+
+    let mut candidates: Vec<&DiscoveredFile> = project::template_files(db, project)
+        .iter()
+        .filter(|discovered| discovered.name == name)
+        .collect();
+    candidates.dedup_by(|left, right| left.path == right.path);
+
+    let discovered = match candidates.as_slice() {
+        [only] => Some(*only),
+        [] => {
+            incomplete.get_or_insert_with(|| {
+                format!("no template of the project is loadable as `{name}`")
+            });
+            None
+        }
+        _ => {
+            incomplete.get_or_insert_with(|| {
+                format!(
+                    "two of the project's template directories hold a `{name}`, so renaming one \
+                     would change which of them the other's name loads"
+                )
+            });
+            None
+        }
+    };
+
+    // the file itself is where the name leads, which is the declaration a
+    // reference list is asked to include or leave out
+    let mut found: Vec<Use> = candidates
+        .iter()
+        .filter_map(|candidate| {
+            Some(Use {
+                file: system_path_to_file(db, &candidate.path).ok()?,
+                range: TextRange::default(),
+                written: Written::Itself,
+                own: candidate.own,
+                template: true,
+                declaration: true,
+            })
+        })
+        .collect();
+
+    let listed = [name];
+    found.extend(bindings(db, &listed));
+    found.extend(python_uses(project::template_uses(db, project), &listed));
+    found.extend(template_uses(db, TEMPLATE_TAGS, &listed, true));
+
+    Loaded {
+        discovered,
+        uses: Uses { found, incomplete },
+    }
+}
+
+// ---------------------------------------------------------------------------
+// a tag or filter name
+// ---------------------------------------------------------------------------
+
+/// every template that writes the tag or filter `name`, and what registers it
+///
+/// a name nothing registers is a builtin, and every `{% if %}` in a project is
+/// no answer to any question, so nothing is found for one.
+pub(super) fn registration(db: &dyn Db, name: &str, filter: bool) -> Uses {
+    let matching = |kind: RegistrationKind| match kind {
+        RegistrationKind::Filter => filter,
+        RegistrationKind::Tag { .. } => !filter,
+    };
+
+    let mut found: Vec<Use> = project::registrations(db, db.project())
+        .iter()
+        .filter(|registration| matching(registration.kind) && registration.name == name)
+        .map(|registration| Use {
+            file: registration.file,
+            range: registration.range,
+            written: Written::Itself,
+            own: true,
+            template: false,
+            declaration: true,
+        })
+        .collect();
+
+    if found.is_empty() {
+        return Uses::default();
+    }
+
+    let written = if filter {
+        TokenKind::FilterName
+    } else {
+        TokenKind::TagName
+    };
+
+    for template in templates(db) {
+        let source = template.source.as_str();
+
+        for token in template.index.lexed().tokens() {
+            if token.kind != written || source[token.range] != *name {
+                continue;
+            }
+
+            found.push(Use {
+                file: template.file,
+                range: token.range,
+                written: Written::Whole,
+                own: template.own,
+                template: true,
+                declaration: false,
+            });
+        }
+    }
+
+    Uses {
+        found,
+        incomplete: None,
+    }
+}
+
+// ---------------------------------------------------------------------------
+// the scans the kinds share
+// ---------------------------------------------------------------------------
+
+/// every constant of the project one of `names` is bound to
+///
+/// a constant is the way a name reaches a position django reads without being
+/// written there — `TEMPLATE = "blog/base.html"` and then a `render(request,
+/// TEMPLATE)`, or a helper nothing here can see at all.
+fn bindings(db: &dyn Db, names: &[&str]) -> Vec<Use> {
+    project::bound_names(db, names)
+        .into_iter()
+        .map(|binding| Use {
+            file: binding.file,
+            range: binding.value,
+            written: Written::Bound(binding.bound_to),
+            own: true,
+            template: false,
+            declaration: false,
+        })
+        .collect()
+}
+
+/// the python positions among `scanned` that name one of `names`
+///
+/// a position whose name is worked out at run time is kept: it names *something*,
+/// and which of the two features that matters to is [`Written::Unknown`].
+fn python_uses(scanned: &[project::NameUse], names: &[&str]) -> Vec<Use> {
+    scanned
+        .iter()
+        .filter(|used| {
+            used.name
+                .as_deref()
+                .is_none_or(|name| names.contains(&name))
+        })
+        .map(|used| Use {
+            file: used.file,
+            range: used.range,
+            written: match (&used.name, used.whole) {
+                (None, _) => Written::Unknown,
+                (Some(_), false) => Written::Pieces,
+                (Some(_), true) => Written::Whole,
+            },
+            own: true,
+            template: false,
+            declaration: false,
+        })
+        .collect()
+}
+
+/// every place a template writes one of `names` as an argument of one of `tags`
+///
+/// `fragment` strips the `#partial` a template reference may carry, which names
+/// something inside the template rather than the template.
+fn template_uses(db: &dyn Db, tags: &[&str], names: &[&str], fragment: bool) -> Vec<Use> {
+    let mut found = Vec::new();
+
+    for template in templates(db) {
+        let source = template.source.as_str();
+        let mut accounted = Vec::new();
+
+        for construct in template.index.lexed().constructs() {
+            if construct.kind != ConstructKind::Tag {
+                continue;
+            }
+            let Some(tag) = construct.name.map(|range| &source[range]) else {
+                continue;
+            };
+            if !tags.contains(&tag) {
+                continue;
+            }
+
+            let Some(token) = arguments(template.index, construct)
+                .iter()
+                .find(|token| matches!(token.kind, TokenKind::Variable | TokenKind::String))
+            else {
+                continue;
+            };
+
+            if token.kind != TokenKind::String {
+                // an installed app working out its own names at render time is
+                // speculation about code nothing here could have rewritten
+                // whatever it said
+                if template.own {
+                    found.push(Use {
+                        file: template.file,
+                        range: token.range,
+                        written: Written::Unknown,
+                        own: true,
+                        template: true,
+                        declaration: false,
+                    });
+                }
+                continue;
+            }
+
+            let contents = string_contents(source, token.range);
+            accounted.push(contents);
+
+            let range = if fragment {
+                strip_fragment(source, contents)
+            } else {
+                contents
+            };
+            if !names.contains(&&source[range]) {
+                continue;
+            }
+
+            found.push(Use {
+                file: template.file,
+                range,
+                written: Written::Whole,
+                own: template.own,
+                template: true,
+                declaration: false,
+            });
+        }
+
+        found.extend(
+            template
+                .index
+                .lexed()
+                .tokens()
+                .iter()
+                .filter(|token| token.kind == TokenKind::String)
+                .map(|token| string_contents(source, token.range))
+                .filter(|range| names.contains(&&source[*range]) && !accounted.contains(range))
+                .map(|range| Use {
+                    file: template.file,
+                    range,
+                    written: Written::Stray,
+                    own: template.own,
+                    template: true,
+                    declaration: false,
+                }),
+        );
+    }
+
+    found
+}
+
+/// a template django can load, and everything a scan needs to read it
+struct Template<'db> {
+    file: File,
+    /// whether it is the project's own, and so a file a rename could edit
+    own: bool,
+    index: &'db TemplateIndex,
+    source: SourceText,
+}
+
+/// every template django could load, the project's own and its installed apps'
+fn templates(db: &dyn Db) -> Vec<Template<'_>> {
+    let mut seen = FxHashSet::default();
+
+    project::template_files(db, db.project())
+        .iter()
+        .filter_map(|discovered| {
+            let file = system_path_to_file(db, &discovered.path).ok()?;
+            seen.insert(file).then(|| Template {
+                file,
+                own: discovered.own,
+                index: template_index(db, file),
+                source: source_text(db, file),
+            })
+        })
+        .collect()
+}
+
+/// the value and contents range of the python string literal spanning `range`
+fn python_literal(db: &dyn Db, file: File, range: TextRange) -> Option<(CompactString, TextRange)> {
+    let parsed = parsed_module(db, file).load(db);
+    let covering = covering_node(parsed.syntax().into(), range);
+
+    let string = covering.ancestors().find_map(|node| match node {
+        AnyNodeRef::ExprStringLiteral(string) => Some(string),
+        _ => None,
+    })?;
+    let [part] = string.value.as_slice() else {
+        return None;
+    };
+
+    Some((string.value.to_str().into(), part.content_range()))
+}
+
+pub(super) fn path_of(db: &dyn Db, file: File) -> String {
+    file.path(db).to_string()
+}
+
+/// put the uses in a stable order, so that two runs answer the same
+pub(super) fn sort(db: &dyn Db, found: &mut [Use]) {
+    found.sort_by(|left, right| {
+        path_of(db, left.file)
+            .cmp(&path_of(db, right.file))
+            .then(left.range.start().cmp(&right.range.start()))
+    });
+}
diff --git a/crates/ty_ide/src/lib.rs b/crates/ty_ide/src/lib.rs
index 0f2fe503ca..7d29fdc8be 100644
--- a/crates/ty_ide/src/lib.rs
+++ b/crates/ty_ide/src/lib.rs
@@ -41,8 +41,10 @@ pub use completion::{
     CompletionSettings, completion,
 };
 pub use django_template::{
-    DisplayTemplateHover, TemplateCompletion, TemplateEdit, TemplateHover, TemplateSymbol,
-    django_template_completions, django_template_document_symbols, django_template_folding_ranges,
+    DisplayTemplateHover, PreparedTemplateRename, TemplateCompletion, TemplateEdit, TemplateHover,
+    TemplateRename, TemplateRenameOutcome, TemplateSymbol, django_prepare_rename,
+    django_references, django_rename, django_template_completions, django_template_diagnostics,
+    django_template_document_symbols, django_template_folding_ranges,
     django_template_goto_definition, django_template_hover, django_template_semantic_tokens,
     is_django_template_path,
 };
diff --git a/crates/ty_python_semantic/src/django_template.rs b/crates/ty_python_semantic/src/django_template.rs
new file mode 100644
index 0000000000..2bd60812ac
--- /dev/null
+++ b/crates/ty_python_semantic/src/django_template.rs
@@ -0,0 +1,315 @@
+//! the lints a django template can report
+//!
+//! a template is not python, so nothing here checks anything: the checks live in
+//! `ty_ide`'s template front end, which is the only place that can read a
+//! template at all. what has to live here is the *declaration* of each rule,
+//! because the lint registry — and with it `[tool.ty.rules]`, the generated
+//! schema and the generated documentation — is this crate's.
+
+use crate::declare_lint;
+use crate::lint::{Level, LintRegistryBuilder, LintStatus};
+
+/// Register the lints a django template can report.
+pub(crate) fn register_lints(registry: &mut LintRegistryBuilder) {
+    registry.register_lint(&UNCLOSED_TEMPLATE_BLOCK);
+    registry.register_lint(&UNMATCHED_TEMPLATE_CLOSE);
+    registry.register_lint(&UNKNOWN_TEMPLATE_LIBRARY);
+    registry.register_lint(&UNKNOWN_TEMPLATE_TAG);
+    registry.register_lint(&UNKNOWN_TEMPLATE_FILTER);
+    registry.register_lint(&UNLOADED_TEMPLATE_LIBRARY);
+    registry.register_lint(&UNRESOLVED_TEMPLATE);
+    registry.register_lint(&UNRESOLVED_STATIC_FILE);
+    registry.register_lint(&UNRESOLVED_ROUTE);
+    registry.register_lint(&INVALID_ROUTE_ARGUMENTS);
+    registry.register_lint(&UNKNOWN_TEMPLATE_BLOCK);
+    registry.register_lint(&TEMPLATE_MEMBER_NEEDS_ARGUMENTS);
+}
+
+declare_lint! {
+    /// ## What it does
+    /// Checks for a block tag in a django template whose closing tag is missing.
+    ///
+    /// ## Why is this bad?
+    /// Django raises `TemplateSyntaxError` when it compiles the template, so the
+    /// page does not render at all.
+    ///
+    /// Only a tag known to open a block is reported: one of django's own, or one
+    /// the project registers with `@register.simple_block_tag`.
+    ///
+    /// ## Examples
+    /// ```django
+    /// {% if user.is_staff %}    {# error: no `{% endif %}` #}
+    ///   <p>hello</p>
+    /// ```
+    pub static UNCLOSED_TEMPLATE_BLOCK = {
+        summary: "detects a django template block tag that is never closed",
+        status: LintStatus::stable("0.0.69"),
+        default_level: Level::Error,
+    }
+}
+
+declare_lint! {
+    /// ## What it does
+    /// Checks for a closing tag in a django template that closes nothing.
+    ///
+    /// ## Why is this bad?
+    /// Django raises `TemplateSyntaxError` when it compiles the template, so the
+    /// page does not render at all.
+    ///
+    /// ## Examples
+    /// ```django
+    /// {% for book in books %}
+    ///   <p>{{ book.title }}</p>
+    /// {% endwith %}    {# error: nothing here opened a `{% with %}` #}
+    /// {% endfor %}
+    /// ```
+    pub static UNMATCHED_TEMPLATE_CLOSE = {
+        summary: "detects a django template closing tag that closes nothing",
+        status: LintStatus::stable("0.0.69"),
+        default_level: Level::Error,
+    }
+}
+
+declare_lint! {
+    /// ## What it does
+    /// Checks for a `{% load %}` of a tag library the project does not have.
+    ///
+    /// ## Why is this bad?
+    /// Django raises `TemplateSyntaxError` when it compiles the template, so the
+    /// page does not render at all.
+    ///
+    /// A library is a `templatetags` module of the project or of one of the apps
+    /// `INSTALLED_APPS` names. Nothing is reported unless the settings module was
+    /// found and every installed app resolved, since a library that cannot be
+    /// reached is not a library that is missing.
+    ///
+    /// ## Examples
+    /// ```django
+    /// {% load blog_xtras %}    {# error: the library is `blog_extras` #}
+    /// ```
+    pub static UNKNOWN_TEMPLATE_LIBRARY = {
+        summary: "detects a `{% load %}` of a library the project does not have",
+        status: LintStatus::stable("0.0.69"),
+        default_level: Level::Error,
+    }
+}
+
+declare_lint! {
+    /// ## What it does
+    /// Checks for a tag no library the template can reach registers.
+    ///
+    /// ## Why is this bad?
+    /// Django raises `TemplateSyntaxError` when it compiles the template, so the
+    /// page does not render at all.
+    ///
+    /// A tag whose library the template has simply not loaded is reported as
+    /// `unloaded-template-library` instead.
+    ///
+    /// ## Examples
+    /// ```django
+    /// {% iff user.is_staff %}    {# error: no such tag #}
+    /// ```
+    pub static UNKNOWN_TEMPLATE_TAG = {
+        summary: "detects a django template tag nothing registers",
+        status: LintStatus::stable("0.0.69"),
+        default_level: Level::Error,
+    }
+}
+
+declare_lint! {
+    /// ## What it does
+    /// Checks for a filter no library the template can reach registers.
+    ///
+    /// ## Why is this bad?
+    /// Django raises `TemplateSyntaxError` when it compiles the template, so the
+    /// page does not render at all.
+    ///
+    /// A filter whose library the template has simply not loaded is reported as
+    /// `unloaded-template-library` instead.
+    ///
+    /// ## Examples
+    /// ```django
+    /// {{ book.title|uppercase }}    {# error: the filter is `upper` #}
+    /// ```
+    pub static UNKNOWN_TEMPLATE_FILTER = {
+        summary: "detects a django template filter nothing registers",
+        status: LintStatus::stable("0.0.69"),
+        default_level: Level::Error,
+    }
+}
+
+declare_lint! {
+    /// ## What it does
+    /// Checks for a tag or filter used without the `{% load %}` it needs.
+    ///
+    /// ## Why is this bad?
+    /// Django raises `TemplateSyntaxError` when it compiles the template, so the
+    /// page does not render at all — the tag exists, but not in this template.
+    ///
+    /// A library named by `TEMPLATES[*]["OPTIONS"]["builtins"]` is loaded into
+    /// every template already and is never reported.
+    ///
+    /// ## Examples
+    /// ```django
+    /// {% static 'css/site.css' %}    {# error: needs `{% load static %}` #}
+    /// ```
+    pub static UNLOADED_TEMPLATE_LIBRARY = {
+        summary: "detects a tag or filter used without the `{% load %}` it needs",
+        status: LintStatus::stable("0.0.69"),
+        default_level: Level::Error,
+    }
+}
+
+declare_lint! {
+    /// ## What it does
+    /// Checks for an `{% extends %}` or `{% include %}` naming a template that
+    /// is not there.
+    ///
+    /// ## Why is this bad?
+    /// Django raises `TemplateDoesNotExist` when it renders the template, so the
+    /// page 500s.
+    ///
+    /// Nothing is reported unless the project's template directories are known:
+    /// a project with no readable settings *and* no directory named `templates`
+    /// is one whose template set cannot be established.
+    ///
+    /// ## Examples
+    /// ```django
+    /// {% extends "blog/bass.html" %}    {# error: the template is `blog/base.html` #}
+    /// ```
+    pub static UNRESOLVED_TEMPLATE = {
+        summary: "detects a reference to a template that is not there",
+        status: LintStatus::stable("0.0.69"),
+        default_level: Level::Error,
+    }
+}
+
+declare_lint! {
+    /// ## What it does
+    /// Checks for a `{% static %}` naming a file that is not there.
+    ///
+    /// ## Why is this bad?
+    /// Django's default storage builds the url from the name without checking it,
+    /// so the page renders and the asset 404s — a failure nothing reports.
+    ///
+    /// A name whose directory holds no discovered file at all is left alone: that
+    /// is what a bundle built into `static/` at deploy time looks like, and it is
+    /// not something the source tree can answer.
+    ///
+    /// ## Examples
+    /// ```django
+    /// {% load static %}
+    /// <link href="{% static 'css/sight.css' %}">    {# warning: it is `css/site.css` #}
+    /// ```
+    pub static UNRESOLVED_STATIC_FILE = {
+        summary: "detects a `{% static %}` naming a file that is not there",
+        status: LintStatus::stable("0.0.69"),
+        default_level: Level::Warn,
+    }
+}
+
+declare_lint! {
+    /// ## What it does
+    /// Checks for a `{% url %}` naming a route the url configuration does not
+    /// have.
+    ///
+    /// ## Why is this bad?
+    /// Django raises `NoReverseMatch` when it renders the template, so the page
+    /// 500s.
+    ///
+    /// The route names are the ones the walk from `ROOT_URLCONF` finds. A project
+    /// that does not say where its url tree starts, or whose tree could not be
+    /// walked in full, reports nothing.
+    ///
+    /// ## Examples
+    /// ```django
+    /// <a href="{% url 'blog:detail' book.pk %}">    {# error: it is `blog:detail` #}
+    /// ```
+    pub static UNRESOLVED_ROUTE = {
+        summary: "detects a `{% url %}` naming a route that does not exist",
+        status: LintStatus::stable("0.0.69"),
+        default_level: Level::Error,
+    }
+}
+
+declare_lint! {
+    /// ## What it does
+    /// Checks the arguments a `{% url %}` passes against the route's own pattern.
+    ///
+    /// ## Why is this bad?
+    /// Django raises `NoReverseMatch` when it renders the template, so the page
+    /// 500s. A route's pattern names the arguments it takes and the converter
+    /// each of them goes through, so a missing, extra or misnamed argument — and
+    /// a literal the converter would reject — is a reversal that cannot match.
+    ///
+    /// Only a route whose whole pattern is known is checked, and a name several
+    /// routes share is reported only when none of them accepts the arguments.
+    ///
+    /// ## Examples
+    /// ```django
+    /// {# path("<int:pk>/", detail, name="detail") #}
+    /// {% url 'detail' %}          {# error: `pk` is missing #}
+    /// {% url 'detail' pk='x' %}   {# error: `pk` goes through `int` #}
+    /// {% url 'detail' pk=1 %}     {# ok #}
+    /// ```
+    pub static INVALID_ROUTE_ARGUMENTS = {
+        summary: "detects a `{% url %}` whose arguments the route cannot take",
+        status: LintStatus::stable("0.0.69"),
+        default_level: Level::Error,
+    }
+}
+
+declare_lint! {
+    /// ## What it does
+    /// Checks for a `{% block %}` overriding a block no ancestor template
+    /// declares.
+    ///
+    /// ## Why is this bad?
+    /// A child template's blocks are rendered by the parent, so a block the
+    /// parent never declares is never rendered — silently, with no error and no
+    /// output.
+    ///
+    /// Only a block written at the top level of a template that `{% extends %}`
+    /// something is reported. A block nested inside another one is rendered as
+    /// part of its enclosing block and needs no declaration above it.
+    ///
+    /// ## Examples
+    /// ```django
+    /// {# base.html declares `content`, and nothing else #}
+    /// {% extends "base.html" %}
+    /// {% block sidebar %}hello{% endblock %}    {# warning: never rendered #}
+    /// ```
+    pub static UNKNOWN_TEMPLATE_BLOCK = {
+        summary: "detects a `{% block %}` no ancestor template declares",
+        status: LintStatus::stable("0.0.69"),
+        default_level: Level::Warn,
+    }
+}
+
+declare_lint! {
+    /// ## What it does
+    /// Checks for a `{{ }}` lookup landing on a method that cannot be called
+    /// without arguments.
+    ///
+    /// ## Why is this bad?
+    /// Django calls whatever a lookup lands on. A method that needs an argument
+    /// cannot be called, so django renders `string_if_invalid` — the empty string
+    /// by default — silently, with no error and no output.
+    ///
+    /// ## Examples
+    /// ```python
+    /// class Book:
+    ///     def headline(self, length: int) -> str: ...
+    ///     def title(self) -> str: ...
+    /// ```
+    ///
+    /// ```django
+    /// {{ book.headline }}    {# warning: renders nothing #}
+    /// {{ book.title }}       {# ok #}
+    /// ```
+    pub static TEMPLATE_MEMBER_NEEDS_ARGUMENTS = {
+        summary: "detects a template lookup landing on a method that needs arguments",
+        status: LintStatus::stable("0.0.69"),
+        default_level: Level::Warn,
+    }
+}
diff --git a/crates/ty_python_semantic/src/lib.rs b/crates/ty_python_semantic/src/lib.rs
index 319fe5678b..498460021c 100644
--- a/crates/ty_python_semantic/src/lib.rs
+++ b/crates/ty_python_semantic/src/lib.rs
@@ -57,6 +57,7 @@ pub use types::{DisplaySettings, TypeQualifiers};
 
 pub mod api_lockfile;
 mod db;
+pub mod django_template;
 mod dunder_all;
 mod fixes;
 pub mod lint;
@@ -91,6 +92,7 @@ pub fn default_lint_registry() -> &'static LintRegistry {
 /// Register all known semantic lints.
 pub fn register_lints(registry: &mut LintRegistryBuilder) {
     types::register_lints(registry);
+    django_template::register_lints(registry);
     registry.register_lint(&UNUSED_IGNORE_COMMENT);
     registry.register_lint(&UNUSED_TYPE_IGNORE_COMMENT);
     registry.register_lint(&IGNORE_COMMENT_UNKNOWN_RULE);
diff --git a/crates/ty_python_semantic/src/types/ide_support.rs b/crates/ty_python_semantic/src/types/ide_support.rs
index f444b65a12..88b3b65126 100644
--- a/crates/ty_python_semantic/src/types/ide_support.rs
+++ b/crates/ty_python_semantic/src/types/ide_support.rs
@@ -2463,6 +2463,18 @@ pub fn no_argument_call_return_type<'db>(db: &'db dyn Db, ty: Type<'db>) -> Opti
         .map(|bindings| bindings.return_type(db))
 }
 
+/// Whether `ty` is a function django would try to call and could not.
+///
+/// Written for django templates, which render `string_if_invalid` — the empty
+/// string by default — for a lookup landing on a method that needs an argument.
+/// Only a function or a method is answered for: anything else that fails to call
+/// is something django's `callable()` test would not have called in the first
+/// place.
+pub fn callable_needs_arguments<'db>(db: &'db dyn Db, ty: Type<'db>) -> bool {
+    matches!(ty, Type::FunctionLiteral(_) | Type::BoundMethod(_))
+        && no_argument_call_return_type(db, ty).is_none()
+}
+
 /// The names `ty`'s own class declares, as opposed to the ones it inherits.
 ///
 /// Written for django templates, where a model's own fields have to be told
diff --git a/crates/ty_server/src/document.rs b/crates/ty_server/src/document.rs
index 4f296e0137..1daccb3786 100644
--- a/crates/ty_server/src/document.rs
+++ b/crates/ty_server/src/document.rs
@@ -12,7 +12,7 @@ use crate::system::AnySystemPath;
 pub(crate) use location::ToLink;
 pub use notebook::NotebookDocument;
 pub(crate) use range::{
-    FileRangeExt, PositionExt, RangeExt, TextSizeExt, ToRangeExt, resolve_file_uri_range,
+    FileRangeExt, LspRange, PositionExt, RangeExt, TextSizeExt, ToRangeExt, resolve_file_uri_range,
 };
 pub use text_document::TextDocument;
 pub(crate) use text_document::{DocumentVersion, LanguageId};
diff --git a/crates/ty_server/src/server/api.rs b/crates/ty_server/src/server/api.rs
index bf21af7d32..d1fc0e9fb6 100644
--- a/crates/ty_server/src/server/api.rs
+++ b/crates/ty_server/src/server/api.rs
@@ -506,11 +506,24 @@ fn respond<Req>(
 {
     if let Err(err) = &result {
         tracing::error!("An error occurred with request ID {id}: {err}");
-        client.show_error_message(format!("ty encountered a problem. {log_guidance}"));
+        report_unexpected_failure(client, err, log_guidance);
     }
     client.respond(id, result);
 }
 
+/// Tells the user the server has a problem, when it actually has one.
+///
+/// A handler that deliberately refuses — a rename it could not carry out in full,
+/// say — answers with an error whose message *is* the explanation, and the editor
+/// shows that message where the user asked. A popup on top of it saying the server
+/// hit a problem would be a lie. This is the same line the request-routing path
+/// draws for the errors it handles.
+pub(super) fn report_unexpected_failure(client: &Client, error: &Error, log_guidance: &str) {
+    if matches!(error.code, ErrorCode::InternalError) {
+        client.show_error_message(format!("ty encountered a problem. {log_guidance}"));
+    }
+}
+
 /// Sends back an error response to the server using a [`Client`] without showing a warning
 /// to the user.
 fn respond_silent_error(id: RequestId, client: &Client, error: lsp_server::ResponseError) {
diff --git a/crates/ty_server/src/server/api/diagnostics.rs b/crates/ty_server/src/server/api/diagnostics.rs
index bacde9c1ac..57535cc52a 100644
--- a/crates/ty_server/src/server/api/diagnostics.rs
+++ b/crates/ty_server/src/server/api/diagnostics.rs
@@ -10,7 +10,7 @@ use lsp_types::{
 use ruff_diagnostics::Applicability;
 use ruff_text_size::Ranged;
 use rustc_hash::{FxHashMap, FxHashSet};
-use ty_ide::{Hint, hints};
+use ty_ide::{Hint, django_template_diagnostics, hints};
 
 use ruff_db::diagnostic::{
     Annotation, DisplayDiagnosticConfig, HyperlinkMode, Severity, SubDiagnostic,
@@ -392,14 +392,6 @@ pub(super) fn compute_diagnostics(
     document: &DocumentHandle,
     encoding: PositionEncoding,
 ) -> Option<Diagnostics> {
-    // A django template is not python. Nothing here would report anything for
-    // one — the type checker never has it in its file set — but going through
-    // the motions would still parse an html file as python for the hints, so it
-    // is turned away up front.
-    if document.is_django_template() {
-        return None;
-    }
-
     let Some(file) = document.notebook_or_file(db) else {
         tracing::info!(
             "No file found for snapshot for `{}`",
@@ -408,6 +400,18 @@ pub(super) fn compute_diagnostics(
         return None;
     };
 
+    // A django template is not python. It is never handed to the type checker or
+    // to the hints — either would parse an html file as python — and what it does
+    // report is the template language's own.
+    if document.is_django_template() {
+        return Some(Diagnostics {
+            items: django_template_diagnostics(db, file),
+            unnecessary_hints: Vec::new(),
+            encoding,
+            file_or_notebook: file,
+        });
+    }
+
     let diagnostics = db.check_file(file);
     let unnecessary_hints = hints(db, file);
 
diff --git a/crates/ty_server/src/server/api/requests/code_action.rs b/crates/ty_server/src/server/api/requests/code_action.rs
index 2a5416610a..aa532d3134 100644
--- a/crates/ty_server/src/server/api/requests/code_action.rs
+++ b/crates/ty_server/src/server/api/requests/code_action.rs
@@ -99,14 +99,36 @@ impl BackgroundDocumentRequestHandler for CodeActionRequestHandler {
             if let Some(diagnostic_id) = diagnostic_id
                 && let Some(range) = diagnostic.range.to_text_range(db, file, uri, encoding)
             {
-                for action in code_actions(db, file, range, &diagnostic_id) {
+                for action in code_actions(
+                    db,
+                    file,
+                    range,
+                    &diagnostic_id,
+                    snapshot.is_django_template(),
+                ) {
+                    // an action that creates a file cannot be written as a text
+                    // edit, so it goes through the resource-operation form
+                    let document_changes = action.create.as_ref().and_then(|path| {
+                        let uri = Uri::from_file_path(path.as_std_path()).ok()?;
+                        Some(vec![lsp_types::DocumentChange::CreateFile(
+                            lsp_types::CreateFile {
+                                uri,
+                                options: None,
+                                annotation_id: None,
+                            },
+                        )])
+                    });
+
                     actions.push(CodeActionResponse::CodeAction(lsp_types::CodeAction {
                         title: action.title,
                         kind: Some(CodeActionKind::QuickFix),
                         diagnostics: Some(vec![diagnostic.clone()]),
                         edit: Some(lsp_types::WorkspaceEdit {
-                            changes: to_lsp_edits(db, file, encoding, action.edits),
-                            document_changes: None,
+                            changes: document_changes
+                                .is_none()
+                                .then(|| to_lsp_edits(db, file, encoding, action.edits))
+                                .flatten(),
+                            document_changes,
                             change_annotations: None,
                         }),
                         is_preferred: Some(action.preferred),
diff --git a/crates/ty_server/src/server/api/requests/prepare_rename.rs b/crates/ty_server/src/server/api/requests/prepare_rename.rs
index 2d2343da3c..08d92a306b 100644
--- a/crates/ty_server/src/server/api/requests/prepare_rename.rs
+++ b/crates/ty_server/src/server/api/requests/prepare_rename.rs
@@ -1,10 +1,15 @@
 use std::borrow::Cow;
 
-use lsp_types::{PrepareRenameParams, PrepareRenameRequest, PrepareRenameResult, Uri};
-use ty_ide::can_rename;
+use anyhow::anyhow;
+use lsp_server::ErrorCode;
+use lsp_types::{
+    PrepareRenameParams, PrepareRenamePlaceholder, PrepareRenameRequest, PrepareRenameResult, Uri,
+};
+use ty_ide::{PreparedTemplateRename, can_rename, django_prepare_rename};
 use ty_project::ProjectDatabase;
 
 use crate::document::{PositionExt, ToRangeExt};
+use crate::server::api::Error;
 use crate::server::api::traits::{
     BackgroundDocumentRequestHandler, RequestHandler, RetriableRequestHandler,
 };
@@ -48,18 +53,29 @@ impl BackgroundDocumentRequestHandler for PrepareRenameRequestHandler {
             return Ok(None);
         };
 
-        let Some(range) = can_rename(db, file, offset) else {
-            return Ok(None);
-        };
+        let template = snapshot.is_django_template();
 
-        let Some(lsp_range) = range
-            .to_lsp_range(db, file, snapshot.encoding())
-            .map(|lsp_range| lsp_range.local_range())
-        else {
-            return Ok(None);
-        };
+        // a python symbol is answered exactly as it was; the django names a
+        // module writes as plain strings are what is left over once it declines
+        if !template && let Some(range) = can_rename(db, file, offset) {
+            return Ok(range
+                .to_lsp_range(db, file, snapshot.encoding())
+                .map(|lsp_range| lsp_range.local_range().into()));
+        }
 
-        Ok(Some(lsp_range.into()))
+        match django_prepare_rename(db, file, offset, template) {
+            None => Ok(None),
+            // the editor shows this rather than offering a rename it could not
+            // finish, which is the whole point of asking first
+            Some(PreparedTemplateRename::Refused(why)) => {
+                Err(Error::new(anyhow!(why), ErrorCode::RequestFailed))
+            }
+            Some(PreparedTemplateRename::Ready { range, placeholder }) => Ok(range
+                .to_lsp_range(db, file, snapshot.encoding())
+                .map(|lsp_range| {
+                    PrepareRenamePlaceholder::new(lsp_range.local_range(), placeholder).into()
+                })),
+        }
     }
 }
 
diff --git a/crates/ty_server/src/server/api/requests/references.rs b/crates/ty_server/src/server/api/requests/references.rs
index daa7a03ee8..dc7dc791d6 100644
--- a/crates/ty_server/src/server/api/requests/references.rs
+++ b/crates/ty_server/src/server/api/requests/references.rs
@@ -2,7 +2,7 @@ use std::borrow::Cow;
 
 use lsp_types::ReferencesRequest;
 use lsp_types::{Location, ReferenceParams, Uri};
-use ty_ide::find_references;
+use ty_ide::{django_references, find_references};
 use ty_project::ProjectDatabase;
 
 use crate::document::{PositionExt, ToLink};
@@ -50,8 +50,17 @@ impl BackgroundDocumentRequestHandler for ReferencesRequestHandler {
         };
 
         let include_declaration = params.context.include_declaration;
+        let template = snapshot.is_django_template();
 
-        let Some(references_result) = find_references(db, file, offset, include_declaration) else {
+        // a python symbol's references are found exactly as they were; the django
+        // names a module writes as plain strings are what is left over once it
+        // declines
+        let found = (!template)
+            .then(|| find_references(db, file, offset, include_declaration))
+            .flatten()
+            .or_else(|| django_references(db, file, offset, include_declaration, template));
+
+        let Some(references_result) = found else {
             return Ok(None);
         };
 
diff --git a/crates/ty_server/src/server/api/requests/rename.rs b/crates/ty_server/src/server/api/requests/rename.rs
index c975df8468..4fcf54c9f1 100644
--- a/crates/ty_server/src/server/api/requests/rename.rs
+++ b/crates/ty_server/src/server/api/requests/rename.rs
@@ -1,12 +1,15 @@
 use std::borrow::Cow;
 use std::collections::HashMap;
 
+use anyhow::anyhow;
+use lsp_server::ErrorCode;
 use lsp_types::RenameRequest;
 use lsp_types::{RenameParams, TextEdit, Uri, WorkspaceEdit};
-use ty_ide::rename;
+use ty_ide::{TemplateRename, TemplateRenameOutcome, django_rename, rename};
 use ty_project::ProjectDatabase;
 
-use crate::document::{PositionExt, ToLink};
+use crate::document::{FileRangeExt, LspRange, PositionExt, ToLink};
+use crate::server::api::Error;
 use crate::server::api::traits::{
     BackgroundDocumentRequestHandler, RequestHandler, RetriableRequestHandler,
 };
@@ -50,34 +53,117 @@ impl BackgroundDocumentRequestHandler for RenameRequestHandler {
             return Ok(None);
         };
 
-        let Some(rename_results) = rename(db, file, offset, &params.new_name) else {
-            return Ok(None);
-        };
+        let template = snapshot.is_django_template();
 
-        // Group text edits by file
-        let mut changes: HashMap<Uri, Vec<TextEdit>> = HashMap::new();
+        // a python symbol is renamed exactly as it was; the django names a module
+        // writes as plain strings are what is left over once it declines
+        if !template && let Some(rename_results) = rename(db, file, offset, &params.new_name) {
+            // Group text edits by file
+            let mut changes: HashMap<Uri, Vec<TextEdit>> = HashMap::new();
 
-        for reference in rename_results {
-            if let Some(location) = reference.to_location(db, snapshot.encoding()) {
-                let edit = TextEdit {
-                    range: location.range,
-                    new_text: params.new_name.clone(),
-                };
+            for reference in rename_results {
+                if let Some(location) = reference.to_location(db, snapshot.encoding()) {
+                    let edit = TextEdit {
+                        range: location.range,
+                        new_text: params.new_name.clone(),
+                    };
 
-                changes.entry(location.uri).or_default().push(edit);
+                    changes.entry(location.uri).or_default().push(edit);
+                }
             }
+
+            if changes.is_empty() {
+                return Ok(None);
+            }
+
+            return Ok(Some(WorkspaceEdit {
+                changes: Some(changes),
+                document_changes: None,
+                change_annotations: None,
+            }));
         }
 
-        if changes.is_empty() {
-            return Ok(None);
+        match django_rename(db, file, offset, &params.new_name, template) {
+            None => Ok(None),
+            Some(TemplateRenameOutcome::Refused(why)) => {
+                Err(Error::new(anyhow!(why), ErrorCode::RequestFailed))
+            }
+            Some(TemplateRenameOutcome::Edits(renamed)) => Ok(django_workspace_edit(
+                db,
+                snapshot,
+                &params.new_name,
+                renamed,
+            )),
         }
+    }
+}
+
+/// the edits a django rename makes, as the client applies them
+///
+/// a rename that moves a file cannot be written as text edits alone, so it goes
+/// through the ordered `document_changes` form — with the edits first, since the
+/// file being moved may be one of the files being edited.
+fn django_workspace_edit(
+    db: &ProjectDatabase,
+    snapshot: &DocumentSnapshot,
+    new_name: &str,
+    renamed: TemplateRename,
+) -> Option<WorkspaceEdit> {
+    let mut changes: HashMap<Uri, Vec<TextEdit>> = HashMap::new();
 
-        Ok(Some(WorkspaceEdit {
+    for edit in renamed.edits {
+        let location = edit
+            .to_lsp_range(db, snapshot.encoding())
+            .and_then(LspRange::into_location)?;
+
+        changes
+            .entry(location.uri)
+            .or_default()
+            .push(lsp_types::TextEdit {
+                range: location.range,
+                new_text: new_name.to_string(),
+            });
+    }
+
+    let Some((from, to)) = renamed.file_rename else {
+        return (!changes.is_empty()).then_some(WorkspaceEdit {
             changes: Some(changes),
             document_changes: None,
             change_annotations: None,
-        }))
-    }
+        });
+    };
+
+    let mut by_file: Vec<(Uri, Vec<TextEdit>)> = changes.into_iter().collect();
+    by_file.sort_by(|(left, _), (right, _)| left.as_str().cmp(right.as_str()));
+
+    let mut document_changes: Vec<lsp_types::DocumentChange> = by_file
+        .into_iter()
+        .map(|(uri, edits)| {
+            lsp_types::TextDocumentEdit {
+                text_document: lsp_types::OptionalVersionedTextDocumentIdentifier {
+                    version: None,
+                    text_document_identifier: lsp_types::TextDocumentIdentifier { uri },
+                },
+                edits: edits.into_iter().map(Into::into).collect(),
+            }
+            .into()
+        })
+        .collect();
+
+    document_changes.push(lsp_types::DocumentChange::RenameFile(
+        lsp_types::RenameFile {
+            old_uri: Uri::from_file_path(from.as_std_path()).ok()?,
+            new_uri: Uri::from_file_path(to.as_std_path()).ok()?,
+            options: None,
+            annotation_id: None,
+        },
+    ));
+
+    Some(WorkspaceEdit {
+        changes: None,
+        document_changes: Some(document_changes),
+        change_annotations: None,
+    })
 }
 
 impl RetriableRequestHandler for RenameRequestHandler {}
diff --git a/crates/ty_server/src/server/api/traits.rs b/crates/ty_server/src/server/api/traits.rs
index 06717523e8..35ae7f674b 100644
--- a/crates/ty_server/src/server/api/traits.rs
+++ b/crates/ty_server/src/server/api/traits.rs
@@ -114,10 +114,7 @@ pub(super) trait BackgroundDocumentRequestHandler: RetriableRequestHandler {
 
         if let Err(err) = &result {
             tracing::error!("An error occurred with request ID {id}: {err}");
-            client.show_error_message(format!(
-                "ty encountered a problem. {}",
-                snapshot.client_name().log_guidance()
-            ));
+            super::report_unexpected_failure(client, err, snapshot.client_name().log_guidance());
         }
 
         client.respond(id, result);
@@ -154,10 +151,7 @@ pub(super) trait BackgroundRequestHandler: RetriableRequestHandler {
 
         if let Err(err) = &result {
             tracing::error!("An error occurred with request ID {id}: {err}");
-            client.show_error_message(format!(
-                "ty encountered a problem. {}",
-                snapshot.client_name().log_guidance()
-            ));
+            super::report_unexpected_failure(client, err, snapshot.client_name().log_guidance());
         }
 
         client.respond(id, result);
diff --git a/crates/ty_server/tests/e2e/django_templates.rs b/crates/ty_server/tests/e2e/django_templates.rs
index 90326ebba7..8abbfca8d0 100644
--- a/crates/ty_server/tests/e2e/django_templates.rs
+++ b/crates/ty_server/tests/e2e/django_templates.rs
@@ -357,3 +357,448 @@ fn an_html_file_inside_a_templates_directory_is_a_template_whatever_the_client_c
 
     Ok(())
 }
+
+/// a view that names a template and reverses a route, both as plain strings
+const WHOLE_VIEWS: &str = "\
+from django.shortcuts import render
+from django.urls import reverse
+
+
+def post(request):
+    reverse('blog:detail')
+    return render(request, 'blog/post.html', {})
+";
+
+/// the same project, with a settings module that makes the indexes authoritative
+///
+/// a rename refuses outright unless the whole project can be read, so nothing
+/// below can share the smaller fixture above.
+fn whole_project(templates: &[(&str, &str)]) -> Result<TestServer> {
+    let mut builder = TestServerBuilder::new()?
+        .with_workspace(SystemPath::new("src"), None)?
+        .with_file(
+            SystemPath::new("src/manage.py"),
+            "import os\n\nos.environ.setdefault('DJANGO_SETTINGS_MODULE', 'project.settings')\n",
+        )?
+        .with_file(SystemPath::new("src/project/__init__.py"), "")?
+        .with_file(
+            SystemPath::new("src/project/settings.py"),
+            "INSTALLED_APPS = ['blog']\n\nTEMPLATES = [{'DIRS': [], 'APP_DIRS': True, 'OPTIONS': {}}]\n\nROOT_URLCONF = 'project.urls'\n",
+        )?
+        .with_file(
+            SystemPath::new("src/project/urls.py"),
+            "from django.urls import include, path\n\nurlpatterns = [path('blog/', include('blog.urls'))]\n",
+        )?
+        .with_file(SystemPath::new("src/blog/__init__.py"), "")?
+        .with_file(
+            SystemPath::new("src/blog/urls.py"),
+            "from django.urls import path\n\napp_name = 'blog'\n\nurlpatterns = [path('<int:pk>/', detail, name='detail')]\n",
+        )?
+        .with_file(SystemPath::new("src/blog/views.py"), WHOLE_VIEWS)?;
+
+    for (path, contents) in templates {
+        builder = builder.with_file(SystemPath::new(path), contents)?;
+    }
+
+    let mut server = builder.build().wait_until_workspaces_are_initialized();
+
+    for (path, contents) in templates {
+        server.open_text_document_as(
+            SystemPath::new(path),
+            contents,
+            1,
+            LanguageKind::new("django-html"),
+        );
+    }
+
+    Ok(server)
+}
+
+/// a uri as the path below the workspace root, so that a test reads the same
+/// wherever it was run
+fn relative(uri: &lsp_types::Uri) -> String {
+    let path = uri.as_str();
+    match path.split_once("/src/") {
+        Some((_, below)) => below.to_string(),
+        None => path.to_string(),
+    }
+}
+
+/// every edit of a workspace edit, as `path:line:column-column -> text`, sorted
+fn rendered(edit: &lsp_types::WorkspaceEdit) -> Vec<String> {
+    let render = |uri: &lsp_types::Uri, edits: &[lsp_types::TextEdit]| -> Vec<String> {
+        edits
+            .iter()
+            .map(|edit| {
+                format!(
+                    "{}:{:03}:{:03}-{:03} -> {}",
+                    relative(uri),
+                    edit.range.start.line,
+                    edit.range.start.character,
+                    edit.range.end.character,
+                    edit.new_text,
+                )
+            })
+            .collect()
+    };
+
+    let mut lines = Vec::new();
+
+    if let Some(changes) = &edit.changes {
+        let mut by_file: Vec<_> = changes.iter().collect();
+        by_file.sort_by_key(|(uri, _)| uri.as_str());
+
+        for (uri, edits) in by_file {
+            lines.extend(render(uri, edits));
+        }
+    }
+
+    for change in edit.document_changes.iter().flatten() {
+        match change {
+            lsp_types::DocumentChange::TextDocumentEdit(document) => {
+                let edits: Vec<lsp_types::TextEdit> = document
+                    .edits
+                    .iter()
+                    .map(|edit| match edit {
+                        lsp_types::Edit::TextEdit(edit) => edit.clone(),
+                        other => panic!("expected a plain text edit, got {other:?}"),
+                    })
+                    .collect();
+                lines.extend(render(
+                    &document.text_document.text_document_identifier.uri,
+                    &edits,
+                ));
+            }
+            lsp_types::DocumentChange::RenameFile(rename) => lines.push(format!(
+                "move {} -> {}",
+                relative(&rename.old_uri),
+                relative(&rename.new_uri),
+            )),
+            other => panic!("expected only edits and a file rename, got {other:?}"),
+        }
+    }
+
+    lines.sort();
+    lines
+}
+
+fn rename_request(
+    server: &mut TestServer,
+    uri: &lsp_types::Uri,
+    position: Position,
+    new_name: &str,
+) -> lsp_types::WorkspaceEdit {
+    server
+        .send_request_await::<lsp_types::RenameRequest>(lsp_types::RenameParams {
+            text_document_position_params: TextDocumentPositionParams {
+                text_document: TextDocumentIdentifier { uri: uri.clone() },
+                position,
+            },
+            new_name: new_name.to_string(),
+            work_done_progress_params: lsp_types::WorkDoneProgressParams::default(),
+        })
+        .expect("a workspace edit")
+}
+
+#[test]
+fn a_block_rename_reaches_the_base_and_every_child() -> Result<()> {
+    let mut server = whole_project(&[
+        (
+            "src/blog/templates/blog/base.html",
+            "{% block content %}{% endblock content %}\n",
+        ),
+        (
+            "src/blog/templates/blog/post.html",
+            "{% extends 'blog/base.html' %}{% block content %}a{% endblock %}\n",
+        ),
+    ])?;
+    let uri = server.file_uri(SystemPath::new("src/blog/templates/blog/post.html"));
+
+    let prepared = server
+        .send_request_await::<lsp_types::PrepareRenameRequest>(lsp_types::PrepareRenameParams {
+            text_document_position_params: TextDocumentPositionParams {
+                text_document: TextDocumentIdentifier { uri: uri.clone() },
+                position: Position::new(0, 40),
+            },
+            work_done_progress_params: lsp_types::WorkDoneProgressParams::default(),
+        })
+        .expect("a prepare rename response");
+
+    assert!(
+        matches!(
+            &prepared,
+            lsp_types::PrepareRenameResult::PrepareRenamePlaceholder(placeholder)
+                if placeholder.placeholder == "content"
+        ),
+        "got {prepared:?}"
+    );
+
+    let edit = rename_request(&mut server, &uri, Position::new(0, 40), "body");
+    assert_eq!(
+        rendered(&edit),
+        [
+            "blog/templates/blog/base.html:000:009-016 -> body",
+            "blog/templates/blog/base.html:000:031-038 -> body",
+            "blog/templates/blog/post.html:000:039-046 -> body",
+        ]
+    );
+
+    Ok(())
+}
+
+#[test]
+fn a_route_rename_reaches_the_declaration_the_python_and_the_template() -> Result<()> {
+    let mut server = whole_project(&[(
+        "src/blog/templates/blog/post.html",
+        "{% url 'blog:detail' pk=1 %}\n",
+    )])?;
+    let uri = server.file_uri(SystemPath::new("src/blog/templates/blog/post.html"));
+
+    let edit = rename_request(&mut server, &uri, Position::new(0, 15), "entry");
+    assert_eq!(
+        rendered(&edit),
+        [
+            "blog/templates/blog/post.html:000:013-019 -> entry",
+            "blog/urls.py:004:047-053 -> entry",
+            "blog/views.py:005:018-024 -> entry",
+        ]
+    );
+
+    Ok(())
+}
+
+#[test]
+fn a_template_rename_moves_the_file_as_well_as_rewriting_its_name() -> Result<()> {
+    let mut server = whole_project(&[
+        ("src/blog/templates/blog/post.html", "<p>a post</p>\n"),
+        (
+            "src/blog/templates/blog/list.html",
+            "{% include 'blog/post.html' %}\n",
+        ),
+    ])?;
+    let uri = server.file_uri(SystemPath::new("src/blog/templates/blog/list.html"));
+
+    let edit = rename_request(&mut server, &uri, Position::new(0, 15), "blog/entry.html");
+    assert_eq!(
+        rendered(&edit),
+        [
+            "blog/templates/blog/list.html:000:012-026 -> blog/entry.html",
+            "blog/views.py:006:028-042 -> blog/entry.html",
+            "move blog/templates/blog/post.html -> blog/templates/blog/entry.html",
+        ]
+    );
+
+    Ok(())
+}
+
+#[test]
+fn a_rename_that_cannot_be_completed_comes_back_as_an_error() -> Result<()> {
+    let mut server = whole_project(&[
+        (
+            "src/blog/templates/blog/dynamic.html",
+            "{% extends parent %}{% block content %}a{% endblock %}\n",
+        ),
+        (
+            "src/blog/templates/blog/base.html",
+            "{% block content %}{% endblock %}\n",
+        ),
+    ])?;
+    let uri = server.file_uri(SystemPath::new("src/blog/templates/blog/base.html"));
+
+    let id =
+        server.send_request::<lsp_types::PrepareRenameRequest>(lsp_types::PrepareRenameParams {
+            text_document_position_params: TextDocumentPositionParams {
+                text_document: TextDocumentIdentifier { uri },
+                position: Position::new(0, 12),
+            },
+            work_done_progress_params: lsp_types::WorkDoneProgressParams::default(),
+        });
+
+    let failure = server
+        .try_await_response::<lsp_types::PrepareRenameRequest>(&id, None)
+        .expect_err("a refusal rather than a rename the editor could not finish");
+
+    assert!(
+        format!("{failure}").contains("render time"),
+        "got {failure}"
+    );
+
+    Ok(())
+}
+
+#[test]
+fn a_route_renamed_from_python_leaves_the_python_services_alone() -> Result<()> {
+    // `reverse('blog:detail')` is a string to python, so the python rename
+    // declines it and the django one answers — while the class beside it is
+    // still renamed the way it always was
+    let mut server = whole_project(&[(
+        "src/blog/templates/blog/post.html",
+        "{% url 'blog:detail' pk=1 %}\n",
+    )])?;
+    let views = SystemPath::new("src/blog/views.py");
+    server.open_text_document(views, WHOLE_VIEWS, 1);
+    let uri = server.file_uri(views);
+
+    let edit = rename_request(&mut server, &uri, Position::new(5, 20), "entry");
+    assert_eq!(
+        rendered(&edit),
+        [
+            "blog/templates/blog/post.html:000:013-019 -> entry",
+            "blog/urls.py:004:047-053 -> entry",
+            "blog/views.py:005:018-024 -> entry",
+        ]
+    );
+
+    Ok(())
+}
+
+/// every location a references request answers with, as `path:line:column`, sorted
+fn located(locations: Option<Vec<lsp_types::Location>>) -> Vec<String> {
+    let mut lines: Vec<String> = locations
+        .unwrap_or_default()
+        .iter()
+        .map(|location| {
+            format!(
+                "{}:{:03}:{:03}",
+                relative(&location.uri),
+                location.range.start.line,
+                location.range.start.character,
+            )
+        })
+        .collect();
+
+    lines.sort();
+    lines
+}
+
+fn references_request(
+    server: &mut TestServer,
+    uri: &lsp_types::Uri,
+    position: Position,
+    include_declaration: bool,
+) -> Vec<String> {
+    located(
+        server.send_request_await::<lsp_types::ReferencesRequest>(lsp_types::ReferenceParams {
+            text_document_position_params: TextDocumentPositionParams {
+                text_document: TextDocumentIdentifier { uri: uri.clone() },
+                position,
+            },
+            work_done_progress_params: lsp_types::WorkDoneProgressParams::default(),
+            partial_result_params: lsp_types::PartialResultParams::default(),
+            context: lsp_types::ReferenceContext {
+                include_declaration,
+            },
+        }),
+    )
+}
+
+#[test]
+fn a_blocks_references_are_every_template_of_the_family_that_declares_it() -> Result<()> {
+    let mut server = whole_project(&[
+        (
+            "src/blog/templates/blog/base.html",
+            "{% block content %}{% endblock content %}\n",
+        ),
+        (
+            "src/blog/templates/blog/post.html",
+            "{% extends 'blog/base.html' %}{% block content %}a{% endblock %}\n",
+        ),
+        (
+            "src/blog/templates/blog/list.html",
+            "{% extends 'blog/base.html' %}{% block content %}b{% endblock %}\n",
+        ),
+    ])?;
+    let uri = server.file_uri(SystemPath::new("src/blog/templates/blog/base.html"));
+
+    assert_eq!(
+        references_request(&mut server, &uri, Position::new(0, 12), true),
+        [
+            "blog/templates/blog/base.html:000:009",
+            "blog/templates/blog/base.html:000:031",
+            "blog/templates/blog/list.html:000:039",
+            "blog/templates/blog/post.html:000:039",
+        ]
+    );
+    assert_eq!(
+        references_request(&mut server, &uri, Position::new(0, 12), false),
+        [
+            "blog/templates/blog/list.html:000:039",
+            "blog/templates/blog/post.html:000:039",
+        ]
+    );
+
+    Ok(())
+}
+
+#[test]
+fn a_templates_references_are_everything_that_renders_it() -> Result<()> {
+    // the cursor is in the template's own text, which names nothing in
+    // particular — "what renders this file" is what is left to answer
+    let mut server = whole_project(&[
+        ("src/blog/templates/blog/post.html", "<p>a post</p>\n"),
+        (
+            "src/blog/templates/blog/list.html",
+            "{% include 'blog/post.html' %}\n",
+        ),
+    ])?;
+    let uri = server.file_uri(SystemPath::new("src/blog/templates/blog/post.html"));
+
+    assert_eq!(
+        references_request(&mut server, &uri, Position::new(0, 5), false),
+        [
+            "blog/templates/blog/list.html:000:012",
+            "blog/views.py:006:028",
+        ]
+    );
+
+    Ok(())
+}
+
+#[test]
+fn a_routes_references_reach_both_languages() -> Result<()> {
+    let mut server = whole_project(&[(
+        "src/blog/templates/blog/post.html",
+        "{% url 'blog:detail' pk=1 %}\n",
+    )])?;
+    let uri = server.file_uri(SystemPath::new("src/blog/templates/blog/post.html"));
+
+    assert_eq!(
+        references_request(&mut server, &uri, Position::new(0, 15), true),
+        [
+            "blog/templates/blog/post.html:000:008",
+            "blog/urls.py:004:047",
+            "blog/views.py:005:013",
+        ]
+    );
+
+    Ok(())
+}
+
+#[test]
+fn a_python_symbols_references_are_found_the_way_they_always_were() -> Result<()> {
+    // `reverse('blog:detail')` is a string to python, so the python references
+    // decline it and the django ones answer — while the parameter beside it is
+    // still found the way it always was
+    let mut server = whole_project(&[(
+        "src/blog/templates/blog/post.html",
+        "{% url 'blog:detail' pk=1 %}\n",
+    )])?;
+    let views = SystemPath::new("src/blog/views.py");
+    server.open_text_document(views, WHOLE_VIEWS, 1);
+    let uri = server.file_uri(views);
+
+    assert_eq!(
+        references_request(&mut server, &uri, Position::new(5, 20), true),
+        [
+            "blog/templates/blog/post.html:000:008",
+            "blog/urls.py:004:047",
+            "blog/views.py:005:013",
+        ]
+    );
+    assert_eq!(
+        references_request(&mut server, &uri, Position::new(4, 10), true),
+        ["blog/views.py:004:009", "blog/views.py:006:018"]
+    );
+
+    Ok(())
+}
diff --git a/crates/ty_wasm/src/lib.rs b/crates/ty_wasm/src/lib.rs
index 6edb68baff..6f354d2480 100644
--- a/crates/ty_wasm/src/lib.rs
+++ b/crates/ty_wasm/src/lib.rs
@@ -686,6 +686,8 @@ impl Workspace {
                     file_id.file,
                     range,
                     diagnostic.inner.id().as_str(),
+                    // the playground has no django template documents
+                    false,
                 )
                 .into_iter()
                 .map(|action| CodeAction {
diff --git a/docs/basedpython/frameworks/django-templates.md b/docs/basedpython/frameworks/django-templates.md
index 40b7565171..0a69b7752b 100644
--- a/docs/basedpython/frameworks/django-templates.md
+++ b/docs/basedpython/frameworks/django-templates.md
@@ -52,6 +52,12 @@ the editor's own html grammar keeps the markup; the server adds what a grammar c
 - `{% block %}` and `{% partialdef %}` names read as the fragments they name, not as variables
 - `{% comment %}` bodies and `{# … #}` are comments; `{% verbatim %}` bodies are plain text
 
+### find references
+
+asking for a name's references answers the reverse of every navigation above: from a `{% block %}`, every template in the family that declares it — including, from a *base* template, every child that overrides it, which is the question you have while editing one. from anywhere in a template, everything that renders it. from a route name, every `{% url %}` and `reverse()`. from a tag or filter, every template that uses it and the `@register` that declares it.
+
+a use a rename could not rewrite is still reported here: knowing where a name is written is useful even where it cannot be changed for you.
+
 ### hover and outline
 
 hovering says what the thing under the caret is: a variable or a path segment as its type, a tag or a filter as its documentation and the `{% load %}` it needs, a `{% block %}` as the block it overrides, an `{% extends %}` as the file it resolves to, a `{% url %}` as its route pattern.
diff --git a/ty.schema.json b/ty.schema.json
index 82071de889..02787c5598 100644
--- a/ty.schema.json
+++ b/ty.schema.json
@@ -1210,6 +1210,16 @@
             }
           ]
         },
+        "invalid-route-arguments": {
+          "title": "detects a `{% url %}` whose arguments the route cannot take",
+          "description": "## What it does\nChecks the arguments a `{% url %}` passes against the route's own pattern.\n\n## Why is this bad?\nDjango raises `NoReverseMatch` when it renders the template, so the page\n500s. A route's pattern names the arguments it takes and the converter\neach of them goes through, so a missing, extra or misnamed argument — and\na literal the converter would reject — is a reversal that cannot match.\n\nOnly a route whose whole pattern is known is checked, and a name several\nroutes share is reported only when none of them accepts the arguments.\n\n## Examples\n```django\n{# path(\"<int:pk>/\", detail, name=\"detail\") #}\n{% url 'detail' %}          {# error: `pk` is missing #}\n{% url 'detail' pk='x' %}   {# error: `pk` goes through `int` #}\n{% url 'detail' pk=1 %}     {# ok #}\n```",
+          "default": "error",
+          "oneOf": [
+            {
+              "$ref": "#/definitions/Level"
+            }
+          ]
+        },
         "invalid-super-argument": {
           "title": "detects invalid arguments for `super()`",
           "description": "## What it does\n\nDetects `super()` calls where:\n\n- the first argument is not a valid class literal, or\n- the second argument is not an instance or subclass of the first argument.\n\n## Why is this bad?\n\n`super(type, obj)` expects:\n\n- the first argument to be a class,\n- and the second argument to satisfy one of the following:\n    - `isinstance(obj, type)` is `True`\n    - `issubclass(obj, type)` is `True`\n\nViolating this relationship will raise a `TypeError` at runtime.\n\n## Examples\n\n```python\nclass A: ...\n\n\nclass B(A): ...\n\n\nsuper(A, B())  # it's okay! `A` satisfies `isinstance(B(), A)`\n\n# `A()` is not a class\nsuper(A(), B())  # error\n\n# `A()` does not satisfy `isinstance(A(), B)`\nsuper(B, A())  # error\n# `A` does not satisfy `issubclass(A, B)`\nsuper(B, A)  # error\n```\n\n## References\n\n- [Python documentation: super()](https://docs.python.org/3/library/functions.html#super)",
@@ -1850,6 +1860,16 @@
             }
           ]
         },
+        "template-member-needs-arguments": {
+          "title": "detects a template lookup landing on a method that needs arguments",
+          "description": "## What it does\nChecks for a `{{ }}` lookup landing on a method that cannot be called\nwithout arguments.\n\n## Why is this bad?\nDjango calls whatever a lookup lands on. A method that needs an argument\ncannot be called, so django renders `string_if_invalid` — the empty string\nby default — silently, with no error and no output.\n\n## Examples\n```python\nclass Book:\n    def headline(self, length: int) -> str: ...\n    def title(self) -> str: ...\n```\n\n```django\n{{ book.headline }}    {# warning: renders nothing #}\n{{ book.title }}       {# ok #}\n```",
+          "default": "warn",
+          "oneOf": [
+            {
+              "$ref": "#/definitions/Level"
+            }
+          ]
+        },
         "too-many-positional-arguments": {
           "title": "detects calls passing too many positional arguments",
           "description": "## What it does\n\nChecks for calls that pass more positional arguments than the callable can accept.\n\n## Why is this bad?\n\nPassing too many positional arguments will raise `TypeError` at runtime.\n\n## Example\n\n```python\ndef f(): ...\n\n\nf(\"foo\")  # error\n```",
@@ -1930,6 +1950,16 @@
             }
           ]
         },
+        "unclosed-template-block": {
+          "title": "detects a django template block tag that is never closed",
+          "description": "## What it does\nChecks for a block tag in a django template whose closing tag is missing.\n\n## Why is this bad?\nDjango raises `TemplateSyntaxError` when it compiles the template, so the\npage does not render at all.\n\nOnly a tag known to open a block is reported: one of django's own, or one\nthe project registers with `@register.simple_block_tag`.\n\n## Examples\n```django\n{% if user.is_staff %}    {# error: no `{% endif %}` #}\n  <p>hello</p>\n```",
+          "default": "error",
+          "oneOf": [
+            {
+              "$ref": "#/definitions/Level"
+            }
+          ]
+        },
         "undeclared-raise": {
           "title": "detects an exception a `raises` clause does not include",
           "description": "## What it does\nChecks for a basedpython function that can raise an exception its\n`raises` clause does not include.\n\n## Why is this bad?\nA `raises` clause is the function's contract about what can escape a\ncall to it. Callers rely on that set to decide what they must handle, so\nan exception outside it escapes somewhere nobody expects it.\n\n## Example\n\n```by\ndef f() raises TypeError:\n    raise ValueError  # error: `ValueError` is not declared\n```",
@@ -1980,6 +2010,66 @@
             }
           ]
         },
+        "unknown-template-block": {
+          "title": "detects a `{% block %}` no ancestor template declares",
+          "description": "## What it does\nChecks for a `{% block %}` overriding a block no ancestor template\ndeclares.\n\n## Why is this bad?\nA child template's blocks are rendered by the parent, so a block the\nparent never declares is never rendered — silently, with no error and no\noutput.\n\nOnly a block written at the top level of a template that `{% extends %}`\nsomething is reported. A block nested inside another one is rendered as\npart of its enclosing block and needs no declaration above it.\n\n## Examples\n```django\n{# base.html declares `content`, and nothing else #}\n{% extends \"base.html\" %}\n{% block sidebar %}hello{% endblock %}    {# warning: never rendered #}\n```",
+          "default": "warn",
+          "oneOf": [
+            {
+              "$ref": "#/definitions/Level"
+            }
+          ]
+        },
+        "unknown-template-filter": {
+          "title": "detects a django template filter nothing registers",
+          "description": "## What it does\nChecks for a filter no library the template can reach registers.\n\n## Why is this bad?\nDjango raises `TemplateSyntaxError` when it compiles the template, so the\npage does not render at all.\n\nA filter whose library the template has simply not loaded is reported as\n`unloaded-template-library` instead.\n\n## Examples\n```django\n{{ book.title|uppercase }}    {# error: the filter is `upper` #}\n```",
+          "default": "error",
+          "oneOf": [
+            {
+              "$ref": "#/definitions/Level"
+            }
+          ]
+        },
+        "unknown-template-library": {
+          "title": "detects a `{% load %}` of a library the project does not have",
+          "description": "## What it does\nChecks for a `{% load %}` of a tag library the project does not have.\n\n## Why is this bad?\nDjango raises `TemplateSyntaxError` when it compiles the template, so the\npage does not render at all.\n\nA library is a `templatetags` module of the project or of one of the apps\n`INSTALLED_APPS` names. Nothing is reported unless the settings module was\nfound and every installed app resolved, since a library that cannot be\nreached is not a library that is missing.\n\n## Examples\n```django\n{% load blog_xtras %}    {# error: the library is `blog_extras` #}\n```",
+          "default": "error",
+          "oneOf": [
+            {
+              "$ref": "#/definitions/Level"
+            }
+          ]
+        },
+        "unknown-template-tag": {
+          "title": "detects a django template tag nothing registers",
+          "description": "## What it does\nChecks for a tag no library the template can reach registers.\n\n## Why is this bad?\nDjango raises `TemplateSyntaxError` when it compiles the template, so the\npage does not render at all.\n\nA tag whose library the template has simply not loaded is reported as\n`unloaded-template-library` instead.\n\n## Examples\n```django\n{% iff user.is_staff %}    {# error: no such tag #}\n```",
+          "default": "error",
+          "oneOf": [
+            {
+              "$ref": "#/definitions/Level"
+            }
+          ]
+        },
+        "unloaded-template-library": {
+          "title": "detects a tag or filter used without the `{% load %}` it needs",
+          "description": "## What it does\nChecks for a tag or filter used without the `{% load %}` it needs.\n\n## Why is this bad?\nDjango raises `TemplateSyntaxError` when it compiles the template, so the\npage does not render at all — the tag exists, but not in this template.\n\nA library named by `TEMPLATES[*][\"OPTIONS\"][\"builtins\"]` is loaded into\nevery template already and is never reported.\n\n## Examples\n```django\n{% static 'css/site.css' %}    {# error: needs `{% load static %}` #}\n```",
+          "default": "error",
+          "oneOf": [
+            {
+              "$ref": "#/definitions/Level"
+            }
+          ]
+        },
+        "unmatched-template-close": {
+          "title": "detects a django template closing tag that closes nothing",
+          "description": "## What it does\nChecks for a closing tag in a django template that closes nothing.\n\n## Why is this bad?\nDjango raises `TemplateSyntaxError` when it compiles the template, so the\npage does not render at all.\n\n## Examples\n```django\n{% for book in books %}\n  <p>{{ book.title }}</p>\n{% endwith %}    {# error: nothing here opened a `{% with %}` #}\n{% endfor %}\n```",
+          "default": "error",
+          "oneOf": [
+            {
+              "$ref": "#/definitions/Level"
+            }
+          ]
+        },
         "unresolved-attribute": {
           "title": "detects references to unresolved attributes",
           "description": "## What it does\n\nChecks for unresolved attributes.\n\n## Why is this bad?\n\nAccessing an unbound attribute will raise an `AttributeError` at runtime.\nAn unresolved attribute is not guaranteed to exist from the type alone,\nso this could also indicate that the object is not of the type that the user expects.\n\n## Examples\n\n```python\nclass A: ...\n\n\n# AttributeError: 'A' object has no attribute 'foo'\nA().foo  # error\n```",
@@ -2030,6 +2120,36 @@
             }
           ]
         },
+        "unresolved-route": {
+          "title": "detects a `{% url %}` naming a route that does not exist",
+          "description": "## What it does\nChecks for a `{% url %}` naming a route the url configuration does not\nhave.\n\n## Why is this bad?\nDjango raises `NoReverseMatch` when it renders the template, so the page\n500s.\n\nThe route names are the ones the walk from `ROOT_URLCONF` finds. A project\nthat does not say where its url tree starts, or whose tree could not be\nwalked in full, reports nothing.\n\n## Examples\n```django\n<a href=\"{% url 'blog:detail' book.pk %}\">    {# error: it is `blog:detail` #}\n```",
+          "default": "error",
+          "oneOf": [
+            {
+              "$ref": "#/definitions/Level"
+            }
+          ]
+        },
+        "unresolved-static-file": {
+          "title": "detects a `{% static %}` naming a file that is not there",
+          "description": "## What it does\nChecks for a `{% static %}` naming a file that is not there.\n\n## Why is this bad?\nDjango's default storage builds the url from the name without checking it,\nso the page renders and the asset 404s — a failure nothing reports.\n\nA name whose directory holds no discovered file at all is left alone: that\nis what a bundle built into `static/` at deploy time looks like, and it is\nnot something the source tree can answer.\n\n## Examples\n```django\n{% load static %}\n<link href=\"{% static 'css/sight.css' %}\">    {# warning: it is `css/site.css` #}\n```",
+          "default": "warn",
+          "oneOf": [
+            {
+              "$ref": "#/definitions/Level"
+            }
+          ]
+        },
+        "unresolved-template": {
+          "title": "detects a reference to a template that is not there",
+          "description": "## What it does\nChecks for an `{% extends %}` or `{% include %}` naming a template that\nis not there.\n\n## Why is this bad?\nDjango raises `TemplateDoesNotExist` when it renders the template, so the\npage 500s.\n\nNothing is reported unless the project's template directories are known:\na project with no readable settings *and* no directory named `templates`\nis one whose template set cannot be established.\n\n## Examples\n```django\n{% extends \"blog/bass.html\" %}    {# error: the template is `blog/base.html` #}\n```",
+          "default": "error",
+          "oneOf": [
+            {
+              "$ref": "#/definitions/Level"
+            }
+          ]
+        },
         "unspecialized-reified-generic": {
           "title": "detects calls to reified generic functions without explicit specialization",
           "description": "## What it does\nChecks for calls to a basedpython reified generic function whose\nspecialization is neither written explicitly nor inferable from the\narguments.\n\n## Why is this bad?\nA function whose type parameter is referenced in a value position is\n*reified*: the type parameter behaves like a positional parameter that\nis filled by the `[...]` specialization step. A bare call is legal only\nwhen the transpiler can inject that step — every type parameter must\nsolve, from the arguments or its PEP 696 default, to a type with a\nruntime spelling at the call site. Otherwise the parameter has no\nvalue at runtime.\n\n## Example\n\n```by\ndef f[T](t: object):\n    print(T)\n\nf[int](1)  # ok\nf(1)       # error: `T` appears nowhere in the signature\n\ndef g[T](t: T):\n    print(T)\n\ng(1)       # ok — transpiles to g[int](1)\n```",

From 8c322ccc7e4ea88e64c98bd0edc6f045ee60fcb3 Mon Sep 17 00:00:00 2001
From: KotlinIsland <65446343+kotlinisland@users.noreply.github.com>
Date: Sat, 8 Aug 2026 21:38:32 +1000
Subject: [PATCH 06/16] real tag discovery, route arguments, signature help,
 symbols and lenses

django's own registry decides which of its tags exist, replacing a table we wrote.
`{% url %}` offers the arguments a route takes and checks them against its
converters. a filter says what it takes, and a loop says what it binds. the
project's django shape is searchable. and a code lens carries both the rendered-by
lens and the `manage.py` runnables
---
 crates/ty_ide/src/completion.rs               |   79 ++
 crates/ty_ide/src/django_template.rs          |  324 ++++-
 crates/ty_ide/src/django_template/builtins.rs |   88 +-
 .../ty_ide/src/django_template/code_lens.rs   |  623 +++++++++
 .../ty_ide/src/django_template/completion.rs  |  456 ++++++-
 .../ty_ide/src/django_template/diagnostics.rs |  346 ++---
 crates/ty_ide/src/django_template/hover.rs    |   14 +-
 .../ty_ide/src/django_template/inlay_hints.rs |  263 ++++
 crates/ty_ide/src/django_template/project.rs  | 1142 +++++++++++++++--
 crates/ty_ide/src/django_template/python.rs   |   88 +-
 .../src/django_template/signature_help.rs     |  465 +++++++
 crates/ty_ide/src/django_template/symbols.rs  |  372 +++++-
 crates/ty_ide/src/inlay_hints.rs              |   24 +
 crates/ty_ide/src/lib.rs                      |   14 +-
 crates/ty_ide/src/workspace_symbols.rs        |   26 +-
 crates/ty_module_resolver/src/resolve.rs      |   12 +
 crates/ty_python_core/src/definition.rs       |    7 +
 crates/ty_server/src/capabilities.rs          |   25 +-
 .../ty_server/src/document/text_document.rs   |   63 +-
 crates/ty_server/src/server/api.rs            |    3 +
 crates/ty_server/src/server/api/requests.rs   |    2 +
 .../src/server/api/requests/code_lens.rs      |  122 ++
 .../server/api/requests/document_symbols.rs   |    4 +-
 .../server/api/requests/execute_command.rs    |  194 ++-
 .../src/server/api/requests/inlay_hints.rs    |   44 +-
 .../src/server/api/requests/signature_help.rs |   56 +-
 .../server/api/requests/workspace_symbols.rs  |    9 +-
 crates/ty_server/src/server/api/symbols.rs    |    6 +-
 crates/ty_server/src/session/options.rs       |    4 +
 .../ty_server/tests/e2e/django_templates.rs   |  377 ++++++
 .../e2e__commands__debug_command.snap         |    2 +
 .../e2e__initialize__initialization.snap      |    9 +-
 ...ialize__initialization_with_workspace.snap |    9 +-
 .../frameworks/django-templates.md            |   36 +-
 34 files changed, 4957 insertions(+), 351 deletions(-)
 create mode 100644 crates/ty_ide/src/django_template/code_lens.rs
 create mode 100644 crates/ty_ide/src/django_template/inlay_hints.rs
 create mode 100644 crates/ty_ide/src/django_template/signature_help.rs
 create mode 100644 crates/ty_server/src/server/api/requests/code_lens.rs

diff --git a/crates/ty_ide/src/completion.rs b/crates/ty_ide/src/completion.rs
index 85adbed100..d0b42f00d0 100644
--- a/crates/ty_ide/src/completion.rs
+++ b/crates/ty_ide/src/completion.rs
@@ -8435,6 +8435,7 @@ router.register("books", BookViewSet, basename="book")
 urlpatterns = [
     path("<int:pk>/", detail, name="detail"),
     path("", index, name="index"),
+    path("<slug:slug>/<int:page>/", paged, name="paged"),
 ]
 "#,
             )
@@ -8528,6 +8529,7 @@ def show(request):
         blog:book-list
         blog:detail
         blog:index
+        blog:paged
         ");
     }
 
@@ -8545,6 +8547,7 @@ url = urls.reverse_lazy("<CURSOR>")
         blog:book-list
         blog:detail
         blog:index
+        blog:paged
         ");
     }
 
@@ -8563,6 +8566,7 @@ def show(request):
         blog:book-list
         blog:detail
         blog:index
+        blog:paged
         ");
     }
 
@@ -8604,6 +8608,81 @@ def show(request):
         assert_snapshot!(builder.build().snapshot(), @"<No completions found>");
     }
 
+    #[test]
+    fn django_reverse_offers_the_arguments_the_route_takes() {
+        let builder = django_test_builder(
+            r#"
+def show(request):
+    return reverse("blog:paged", kwargs={"<CURSOR>"})
+"#,
+        );
+
+        assert_snapshot!(builder.build().snapshot(), @"
+        page
+        slug
+        ");
+    }
+
+    #[test]
+    fn django_reverse_does_not_offer_an_argument_already_given() {
+        let builder = django_test_builder(
+            r#"
+def show(request):
+    return reverse("blog:paged", kwargs={"slug": "a", "<CURSOR>": 1})
+"#,
+        );
+
+        assert_snapshot!(builder.build().snapshot(), @"page");
+    }
+
+    #[test]
+    fn django_reverse_offers_no_argument_for_a_route_that_takes_none() {
+        let builder = django_test_builder(
+            r#"
+def show(request):
+    return reverse("blog:index", kwargs={"<CURSOR>"})
+"#,
+        );
+
+        assert_snapshot!(builder.build().snapshot(), @"<No completions found>");
+    }
+
+    #[test]
+    fn django_reverse_offers_no_argument_for_a_route_that_is_not_there() {
+        let builder = django_test_builder(
+            r#"
+def show(request):
+    return reverse("blog:missing", kwargs={"<CURSOR>"})
+"#,
+        );
+
+        assert_snapshot!(builder.build().snapshot(), @"<No completions found>");
+    }
+
+    #[test]
+    fn django_a_value_in_a_reverses_kwargs_names_no_argument() {
+        let builder = django_test_builder(
+            r#"
+def show(request):
+    return reverse("blog:paged", kwargs={"slug": "<CURSOR>"})
+"#,
+        );
+
+        assert_snapshot!(builder.build().snapshot(), @"<No completions found>");
+    }
+
+    #[test]
+    fn django_a_dict_that_is_not_a_reverses_kwargs_names_no_argument() {
+        let builder = django_test_builder(
+            r#"
+def show(request):
+    return reverse("blog:paged", query={"<CURSOR>"})
+"#,
+        );
+
+        assert_snapshot!(builder.build().snapshot(), @"<No completions found>");
+    }
+
     #[test]
     fn typevar_with_upper_bound() {
         let builder = completion_test_builder(
diff --git a/crates/ty_ide/src/django_template.rs b/crates/ty_ide/src/django_template.rs
index f455a7f259..08c32ed792 100644
--- a/crates/ty_ide/src/django_template.rs
+++ b/crates/ty_ide/src/django_template.rs
@@ -14,12 +14,14 @@
 //! and it is what lets the python services see them for what they are.
 
 mod builtins;
+mod code_lens;
 mod completion;
 mod diagnostics;
 mod folding;
 mod goto;
 mod hover;
 mod index;
+mod inlay_hints;
 mod lexer;
 mod project;
 mod python;
@@ -27,16 +29,20 @@ mod references;
 mod rename;
 mod resolve;
 mod semantic_tokens;
+mod signature_help;
 mod symbols;
 mod uses;
 
+pub use code_lens::{DjangoCodeLens, DjangoLensAction, DjangoLensTarget};
 pub use completion::{TemplateCompletion, TemplateEdit};
 pub use hover::{DisplayTemplateHover, TemplateHover};
+pub use inlay_hints::{TemplateInlayHint, TemplateInlayHintKind};
 pub(crate) use python::{
     string_completions as django_string_completions, string_definition as django_string_definition,
 };
 pub use rename::{PreparedTemplateRename, TemplateRename, TemplateRenameOutcome};
-pub use symbols::TemplateSymbol;
+pub use signature_help::TemplateSignature;
+pub use symbols::{DjangoSymbol, TemplateSymbol};
 
 use ruff_db::diagnostic::Diagnostic;
 use ruff_db::files::File;
@@ -49,7 +55,7 @@ use ty_python_semantic::lint::LintId;
 
 use crate::code_action::QuickFix;
 use crate::semantic_tokens::SemanticTokens;
-use crate::{FoldingRange, NavigationTargets, RangedValue, ReferenceTarget};
+use crate::{FoldingRange, InlayHintSettings, NavigationTargets, RangedValue, ReferenceTarget};
 
 use index::TemplateIndex;
 
@@ -62,7 +68,13 @@ const MAX_INHERITANCE_DEPTH: usize = 16;
 /// whatever path it is given — so this list only decides what the server will
 /// *offer* template support for when the editor hasn't already told it the file
 /// is a template.
-const TEMPLATE_EXTENSIONS: &[&str] = &["html", "htm", "txt", "xml", "django", "dj", "jinja"];
+///
+/// `.jinja` is deliberately not here. jinja is a different language that reads
+/// alike, and everything in this module answers as django: a `{% set %}`, a
+/// `{% macro %}` or a `|default("x")` is correct jinja that django's tag and
+/// filter tables know nothing about, so claiming a jinja file means reporting
+/// correct code as wrong. we do not support jinja, so we do not claim its files.
+const TEMPLATE_EXTENSIONS: &[&str] = &["html", "htm", "txt", "xml", "django", "dj"];
 
 /// the directory name django's app-directories loader looks in
 const TEMPLATE_DIRECTORY: &str = "templates";
@@ -138,6 +150,14 @@ pub fn django_template_document_symbols(db: &dyn Db, file: File) -> Vec<Template
     symbols::document_symbols(template_index(db, file))
 }
 
+/// every django thing of the project whose name matches `query`
+pub(crate) fn django_workspace_symbols(
+    db: &dyn Db,
+    query: &crate::symbols::QueryPattern,
+) -> Vec<DjangoSymbol> {
+    symbols::workspace_symbols(db, query)
+}
+
 /// the foldable ranges of `file`, read as a django template
 pub fn django_template_folding_ranges(db: &dyn Db, file: File) -> Vec<FoldingRange> {
     let source = source_text(db, file);
@@ -247,6 +267,60 @@ pub fn django_references(
     references::references(db, file, offset, include_declaration, template)
 }
 
+/// what the filter argument at `offset` of `file` takes, read as a django
+/// template
+pub fn django_template_signature_help(
+    db: &dyn Db,
+    file: File,
+    offset: TextSize,
+) -> Option<TemplateSignature> {
+    let source = source_text(db, file);
+    signature_help::signature_help(db, template_index(db, file), source.as_str(), offset)
+}
+
+/// the hints `range` of `file` shows, read as a django template
+pub fn django_template_inlay_hints(
+    db: &dyn Db,
+    file: File,
+    range: TextRange,
+    settings: &InlayHintSettings,
+) -> Vec<TemplateInlayHint> {
+    let source = source_text(db, file);
+    inlay_hints::inlay_hints(
+        db,
+        file,
+        template_index(db, file),
+        source.as_str(),
+        range,
+        settings,
+    )
+}
+
+/// the project's `manage.py`, django's own entry point
+///
+/// the lenses above say what to run through it; this is what a caller that has to
+/// actually run one needs, and a project without one is a project none of them
+/// apply to.
+pub fn django_manage_script(db: &dyn Db) -> Option<File> {
+    *project::manage_file(db, db.project())
+}
+
+/// the lenses `file` shows, read as a django template
+///
+/// this is the view side of the join: a template is told what renders it, which
+/// is the one thing about itself it cannot say.
+pub fn django_template_code_lenses(db: &dyn Db, file: File) -> Vec<DjangoCodeLens> {
+    code_lens::template_code_lenses(db, file)
+}
+
+/// the lenses `file` shows, read as one of the project's python modules
+///
+/// these are the `manage.py` invocations that apply to the file, and a module
+/// django gives no role to has none of them.
+pub fn django_python_code_lenses(db: &dyn Db, file: File) -> Vec<DjangoCodeLens> {
+    code_lens::python_code_lenses(db, file)
+}
+
 /// the completions for `offset` in `file`, read as a django template
 pub fn django_template_completions(
     db: &dyn Db,
@@ -264,7 +338,8 @@ pub(crate) mod tests {
     use ruff_db::system::{DbWithTestSystem, DbWithWritableSystem, SystemPath, SystemPathBuf};
     use ruff_python_ast::PythonVersion;
     use ruff_python_trivia::textwrap::dedent;
-    use ruff_text_size::{Ranged, TextSize};
+    use ruff_text_size::{Ranged, TextLen, TextRange, TextSize};
+    use std::ops::Range;
     use ty_module_resolver::SearchPathSettings;
     use ty_project::{ProjectMetadata, TestDb};
     use ty_python_core::platform::PythonPlatform;
@@ -273,13 +348,107 @@ pub(crate) mod tests {
 
     use crate::MarkupKind;
 
+    use crate::InlayHintSettings;
+
     use super::{
-        PreparedTemplateRename, TemplateRenameOutcome, TemplateSymbol, django_prepare_rename,
-        django_references, django_rename, django_template_completions, django_template_diagnostics,
+        DjangoLensAction, PreparedTemplateRename, TemplateRenameOutcome, TemplateSymbol,
+        django_prepare_rename, django_python_code_lenses, django_references, django_rename,
+        django_template_code_lenses, django_template_completions, django_template_diagnostics,
         django_template_document_symbols, django_template_folding_ranges,
-        django_template_goto_definition, django_template_hover, is_django_template_path,
+        django_template_goto_definition, django_template_hover, django_template_inlay_hints,
+        django_template_signature_help, is_django_template_path,
     };
 
+    /// a mock django whose implicit builtins are there to be read
+    ///
+    /// what it registers differs from the builtin table deliberately, and in both
+    /// directions: it has a `{% squish %}` and a `|shorten` the table has never
+    /// heard of, and it has no `{% lorem %}` or `|slugify` though the table does.
+    /// that is what makes it stand in for a django the table has drifted from.
+    pub(crate) const DJANGO_BUILTINS: &[(&str, &str)] = &[
+        ("django/__init__.py", ""),
+        ("django/template/__init__.py", ""),
+        (
+            "django/template/defaulttags.py",
+            "
+            from django.template import Library
+
+            register = Library()
+
+            @register.tag('for')
+            def do_for(parser, token): ...
+
+            @register.tag('if')
+            def do_if(parser, token): ...
+
+            @register.tag
+            def squish(parser, token):
+                '''squishes its body.'''
+            ",
+        ),
+        (
+            "django/template/defaultfilters.py",
+            "
+            from django.template import Library
+
+            register = Library()
+
+            @register.filter(is_safe=True)
+            def upper(value): ...
+
+            @register.filter
+            def shorten(value, arg): ...
+            ",
+        ),
+        (
+            "django/template/loader_tags.py",
+            "
+            from django.template import Library
+
+            register = Library()
+
+            @register.tag('block')
+            def do_block(parser, token): ...
+
+            @register.tag('extends')
+            def do_extends(parser, token): ...
+
+            @register.tag('include')
+            def do_include(parser, token): ...
+            ",
+        ),
+    ];
+
+    /// a mock django whose model base and admin machinery are there to be
+    /// resolved
+    ///
+    /// what matters about it is where the classes are *declared*: a `Model` or a
+    /// `ModelAdmin` counts as django's own because the module it comes from is
+    /// django's, never because of the name written at the point of use.
+    pub(crate) const DJANGO_ADMIN: &[(&str, &str)] = &[
+        ("django/__init__.py", ""),
+        ("django/db/__init__.py", ""),
+        ("django/db/models/__init__.py", "class Model: ...\n"),
+        ("django/contrib/__init__.py", ""),
+        (
+            "django/contrib/admin/__init__.py",
+            "
+            class AdminSite:
+                def register(self, model_or_iterable, admin_class=None, **options): ...
+
+            class ModelAdmin: ...
+
+            class InlineModelAdmin: ...
+
+            class TabularInline(InlineModelAdmin): ...
+
+            site = AdminSite()
+
+            def register(*models, site=None): ...
+            ",
+        ),
+    ];
+
     /// a project whose files are written out, with the cursor marked by
     /// `<CURSOR>` in at most one of them
     ///
@@ -408,6 +577,29 @@ pub(crate) mod tests {
                 .collect()
         }
 
+        /// the workspace symbols matching `query`, as `container name [path]`
+        ///
+        /// what python contributes is rendered under `python`, so that a test
+        /// says both what django added and what it left alone. the order is the
+        /// order the files were walked in, which is no order at all, so it is
+        /// sorted here rather than asserted on.
+        pub(crate) fn workspace_symbols(&self, query: &str) -> Vec<String> {
+            let mut found: Vec<String> = crate::workspace_symbols(&self.db, query)
+                .into_iter()
+                .map(|found| {
+                    format!(
+                        "{} {} [{}]",
+                        found.container.unwrap_or("python"),
+                        found.symbol.name,
+                        // the memory file system reports the host's separator
+                        found.file.path(&self.db).to_string().replace('\\', "/"),
+                    )
+                })
+                .collect();
+            found.sort();
+            found
+        }
+
         /// the labels of the completions at the cursor, in the order offered
         pub(crate) fn completions(&self) -> Vec<String> {
             django_template_completions(&self.db, self.file, self.offset)
@@ -455,6 +647,74 @@ pub(crate) mod tests {
                 .unwrap_or_default()
         }
 
+        /// the signature help at the cursor, as
+        /// `label [parameter] — documentation`
+        pub(crate) fn signature(&self) -> String {
+            let Some(signature) = django_template_signature_help(&self.db, self.file, self.offset)
+            else {
+                return "no signature".to_string();
+            };
+
+            let parameter = signature
+                .parameter
+                .map(|parameter| format!(" [{parameter}]"))
+                .unwrap_or_default();
+            let documentation = signature
+                .documentation
+                .map(|documentation| format!(" — {documentation}"))
+                .unwrap_or_default();
+
+            format!("{}{parameter}{documentation}", signature.label)
+        }
+
+        /// every hint of the whole template, as ``kind at `text`: `label` ``
+        pub(crate) fn hints(&self) -> Vec<String> {
+            let source = ruff_db::source::source_text(&self.db, self.file);
+            self.rendered_hints(
+                TextRange::up_to(source.text_len()),
+                &InlayHintSettings::default(),
+            )
+        }
+
+        /// the same, restricted to a byte range of the template
+        pub(crate) fn hints_in(&self, range: Range<u32>) -> Vec<String> {
+            self.rendered_hints(
+                TextRange::new(range.start.into(), range.end.into()),
+                &InlayHintSettings::default(),
+            )
+        }
+
+        /// the same, with only the settings `enable` turns on
+        pub(crate) fn hints_with(
+            &self,
+            enable: impl FnOnce(&mut InlayHintSettings),
+        ) -> Vec<String> {
+            let mut settings = InlayHintSettings::none();
+            enable(&mut settings);
+
+            let source = ruff_db::source::source_text(&self.db, self.file);
+            self.rendered_hints(TextRange::up_to(source.text_len()), &settings)
+        }
+
+        fn rendered_hints(&self, range: TextRange, settings: &InlayHintSettings) -> Vec<String> {
+            let source = ruff_db::source::source_text(&self.db, self.file);
+
+            django_template_inlay_hints(&self.db, self.file, range, settings)
+                .into_iter()
+                .map(|hint| {
+                    let line_start = source.as_str()[..usize::from(hint.position)]
+                        .rfind('\n')
+                        .map_or(0, |index| index + 1);
+                    let anchored = source.as_str()[line_start..usize::from(hint.position)]
+                        .rsplit([' ', '{', '%'])
+                        .next()
+                        .unwrap_or_default();
+
+                    format!("{:?} at `{anchored}`: `{}`", hint.kind, hint.label)
+                })
+                .collect()
+        }
+
         /// the template's outline, one line per symbol, nesting indented
         pub(crate) fn symbols(&self) -> Vec<String> {
             fn render(symbols: &[TemplateSymbol], depth: usize, lines: &mut Vec<String>) {
@@ -596,6 +856,44 @@ pub(crate) mod tests {
                 .collect()
         }
 
+        /// every lens of the file under test, as `title -> what it does`
+        ///
+        /// which of the two implementations answers is the same question the
+        /// server asks, so the harness asks it the same way.
+        pub(crate) fn lenses(&self) -> Vec<String> {
+            let lenses = if self.is_template() {
+                django_template_code_lenses(&self.db, self.file)
+            } else {
+                django_python_code_lenses(&self.db, self.file)
+            };
+
+            lenses
+                .into_iter()
+                .map(|lens| {
+                    let action = match lens.action {
+                        DjangoLensAction::Run(arguments) => {
+                            format!("manage.py {}", arguments.join(" "))
+                        }
+                        DjangoLensAction::Navigate(targets) => targets
+                            .iter()
+                            .map(|target| {
+                                let source = ruff_db::source::source_text(&self.db, target.file);
+                                format!(
+                                    "{}:{}",
+                                    // the memory file system reports the host's separator
+                                    target.file.path(&self.db).to_string().replace('\\', "/"),
+                                    &source[target.range],
+                                )
+                            })
+                            .collect::<Vec<_>>()
+                            .join(", "),
+                    };
+
+                    format!("{} -> {action}", lens.title)
+                })
+                .collect()
+        }
+
         /// each foldable range, as the tags that open and close it
         pub(crate) fn folds(&self) -> Vec<String> {
             let source = ruff_db::source::source_text(&self.db, self.file);
@@ -636,4 +934,16 @@ pub(crate) mod tests {
             "/app/templates/views.py"
         )));
     }
+
+    #[test]
+    fn a_jinja_file_is_not_claimed_as_a_django_template() {
+        // see `TEMPLATE_EXTENSIONS`: answering a jinja file as django reports its
+        // correct code as wrong
+        assert!(!is_django_template_path(SystemPath::new(
+            "/app/templates/page.jinja"
+        )));
+        assert!(!is_django_template_path(SystemPath::new(
+            "/app/templates/page.html.jinja"
+        )));
+    }
 }
diff --git a/crates/ty_ide/src/django_template/builtins.rs b/crates/ty_ide/src/django_template/builtins.rs
index 632a771cd6..7f9fabb506 100644
--- a/crates/ty_ide/src/django_template/builtins.rs
+++ b/crates/ty_ide/src/django_template/builtins.rs
@@ -4,10 +4,22 @@
 //! and the libraries shipped in `django.templatetags` register. a project's own
 //! tags and filters are discovered from its source instead — see [`super::project`].
 //!
-//! the tables carry the block structure (which tag closes which, and which tags
-//! may appear in between) because the completions and the index both need it: a
-//! `{% for %}` without the knowledge that `{% empty %}` belongs inside it would
-//! either close the block early or never offer `{% empty %}` at all.
+//! the tables are a *fallback*, not an authority. django's own tags and filters
+//! are discovered from the installed django like anything else, and where that
+//! discovery succeeds it decides which names exist and which library each comes
+//! from — see [`provided_by_django`]. a table written by hand drifts as django
+//! moves, and has: `{% partialdef %}` was third-party until django 6.0 made it a
+//! builtin, and the table said the wrong thing for a while.
+//!
+//! what the tables carry that discovery cannot is the block structure (which tag
+//! closes which, and which tags may appear in between) and the documentation.
+//! both are needed: a `{% for %}` without the knowledge that `{% empty %}`
+//! belongs inside it would either close the block early or never offer
+//! `{% empty %}` at all.
+
+use ty_project::Db;
+
+use super::project::{self, RegistrationKind};
 
 /// a builtin template tag
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
@@ -49,10 +61,76 @@ pub(crate) fn end_tag_for(name: &str) -> Option<&'static str> {
     tag(name).and_then(|tag| tag.closed_by)
 }
 
+/// how django's own build hands a name to a template
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub(crate) enum Provided<'a> {
+    /// every template has it, with no `{% load %}` written
+    Always,
+    /// the library that has to be loaded before it can be used
+    By(&'a str),
+}
+
+impl<'a> Provided<'a> {
+    /// the library a template has to load first, where there is one
+    pub(crate) fn library(self) -> Option<&'a str> {
+        match self {
+            Self::Always => None,
+            Self::By(library) => Some(library),
+        }
+    }
+}
+
+/// how django provides the tag or filter `name`, or `None` where it does not
+/// provide it at all
+///
+/// where the project's own django can be read, it is that django which decides
+/// both whether a name exists and which library it comes from; the tables above
+/// then only supply what discovery has no way to see. where it cannot be read —
+/// no settings module, no resolvable django — the tables are all there is, and
+/// answer on their own exactly as they did before.
+pub(crate) fn provided_by_django<'db>(
+    db: &'db dyn Db,
+    name: &str,
+    is_filter: bool,
+) -> Option<Provided<'db>> {
+    let registered = project::registrations(db, db.project())
+        .iter()
+        .find(|registration| {
+            registration.django
+                && registration.name == name
+                && (registration.kind == RegistrationKind::Filter) == is_filter
+        })
+        .map(|registration| {
+            if registration.always_loaded {
+                Provided::Always
+            } else {
+                Provided::By(registration.library.as_str())
+            }
+        });
+
+    // a django that was read and does not register the name is a django the name
+    // is not in, and its silence is as much an answer as its registrations are
+    if registered.is_some() || project::django_is_authoritative(db, db.project()) {
+        return registered;
+    }
+
+    let library = if is_filter {
+        filter(name).map(|filter| filter.library)
+    } else {
+        tag(name).map(|tag| tag.library)
+    }?;
+
+    Some(match library {
+        None => Provided::Always,
+        Some(library) => Provided::By(library),
+    })
+}
+
 /// the libraries a `{% load %}` can name
 ///
 /// every one of them ships with django. a tag or filter the project registers is
-/// discovered from its source instead, and named by its module.
+/// discovered from its source instead, and named by its module — as are django's
+/// own, wherever django itself can be read.
 pub(crate) const LIBRARIES: &[&str] = &["cache", "i18n", "l10n", "static", "tz"];
 
 pub(crate) const TAGS: &[Tag] = &[
diff --git a/crates/ty_ide/src/django_template/code_lens.rs b/crates/ty_ide/src/django_template/code_lens.rs
new file mode 100644
index 0000000000..7862d154f5
--- /dev/null
+++ b/crates/ty_ide/src/django_template/code_lens.rs
@@ -0,0 +1,623 @@
+//! the code lenses a django project puts above its own files
+//!
+//! two unrelated things share the request. a template gets told which views
+//! render it, which is a fact only the project-wide scan in [`super::project`]
+//! holds. a python file gets the `manage.py` invocations that apply to it — the
+//! test it declares, the migration it is, the app whose models it declares —
+//! each of which is a command a developer would otherwise type out by hand, and
+//! each of which the server already knows exactly.
+//!
+//! nothing here answers for a file django has no role for. an ordinary python
+//! module in a django project gets no lens, and every file of a project with no
+//! `manage.py` gets no runnable, since a runnable that cannot be run is worse
+//! than none at all.
+
+use compact_str::{CompactString, ToCompactString};
+use ruff_db::files::File;
+use ruff_db::parsed::parsed_module;
+use ruff_db::system::SystemPath;
+use ruff_python_ast::{self as ast, Stmt};
+use ruff_text_size::{Ranged, TextRange};
+use ty_module_resolver::file_to_module;
+use ty_project::Db;
+
+use super::project::{
+    self, MIGRATIONS_PACKAGE, MODELS_MODULE, TEST_METHOD_PREFIX, is_test_class, manage_file,
+};
+use super::resolve;
+
+/// where a lens with nothing above it sits
+///
+/// a file-level lens belongs on the first line, and a template's first line is
+/// as likely as not to be a `{% extends %}` the lens must not cover.
+const FILE_HEADER: TextRange = TextRange::new(
+    ruff_text_size::TextSize::new(0),
+    ruff_text_size::TextSize::new(0),
+);
+
+/// something a code lens offers to do
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum DjangoLensAction {
+    /// go to these definitions
+    ///
+    /// several are as ordinary as one — a template rendered by two views has two
+    /// places to go — so this is always a list, and the client decides whether to
+    /// jump or to offer a choice.
+    Navigate(Vec<DjangoLensTarget>),
+    /// run `manage.py` with these arguments
+    Run(Vec<CompactString>),
+}
+
+/// a place a lens can navigate to
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct DjangoLensTarget {
+    pub file: File,
+    pub range: TextRange,
+}
+
+/// one lens of a file
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct DjangoCodeLens {
+    /// the range the lens sits above
+    pub range: TextRange,
+    pub title: String,
+    pub action: DjangoLensAction,
+}
+
+/// the lenses of `file`, read as a django template
+///
+/// the only thing a template can be told from outside itself is what renders it,
+/// so a template nothing renders gets nothing rather than a lens saying so.
+pub(super) fn template_code_lenses(db: &dyn Db, file: File) -> Vec<DjangoCodeLens> {
+    let Some(name) = resolve::template_name(db, file) else {
+        return Vec::new();
+    };
+
+    let mut views: Vec<(CompactString, DjangoLensTarget)> = Vec::new();
+
+    for context in project::template_contexts(db, db.project())
+        .iter()
+        .filter(|context| context.template == name)
+    {
+        let Some(view) = &context.view else { continue };
+        let Some(module) = file_to_module(db, view.file) else {
+            continue;
+        };
+
+        let dotted = format!("{}.{}", module.name(db), view.path).to_compact_string();
+        let target = DjangoLensTarget {
+            file: view.file,
+            range: view.range,
+        };
+
+        if !views.iter().any(|(name, _)| *name == dotted) {
+            views.push((dotted, target));
+        }
+    }
+
+    if views.is_empty() {
+        return Vec::new();
+    }
+
+    // the scan walks the project's files in no order at all, and a lens that
+    // reorders itself between two requests reads as a lens that changed
+    views.sort_by(|(left, _), (right, _)| left.cmp(right));
+
+    let names: Vec<&str> = views.iter().map(|(name, _)| name.as_str()).collect();
+
+    vec![DjangoCodeLens {
+        range: FILE_HEADER,
+        title: format!("rendered by {}", names.join(", ")),
+        action: DjangoLensAction::Navigate(views.into_iter().map(|(_, target)| target).collect()),
+    }]
+}
+
+/// the lenses of `file`, read as one of the project's python modules
+///
+/// every one of these runs `manage.py`, so a project without one has none of
+/// them. a module django gives no role to has none either, whether or not the
+/// project has a `manage.py`.
+pub(super) fn python_code_lenses(db: &dyn Db, file: File) -> Vec<DjangoCodeLens> {
+    if manage_file(db, db.project()).is_none() {
+        return Vec::new();
+    }
+    let Some(path) = file.path(db).as_system_path() else {
+        return Vec::new();
+    };
+
+    let mut lenses = Vec::new();
+
+    // a migration is addressed by path rather than by module name because it does
+    // not have one: django numbers migrations, and `0001_initial` is no python
+    // identifier however importable the file is by other means
+    if let Some((app, migration)) = split_path(path, MIGRATIONS_PACKAGE)
+        && let Some(migration) = migration
+    {
+        lenses.push(runnable(
+            format!("migrate to {migration}"),
+            ["migrate", app, migration],
+        ));
+        lenses.push(runnable(
+            "show sql".to_string(),
+            ["sqlmigrate", app, migration],
+        ));
+    }
+
+    // a `models.py` of an app that declares no model has nothing to make a
+    // migration from, and django's own `models.py` scaffold is exactly that file
+    if let Some((app, _)) = split_path(path, MODELS_MODULE)
+        && !project::django_classes_in_file(db, file).is_empty()
+    {
+        lenses.push(runnable(
+            format!("make migrations for {app}"),
+            ["makemigrations", app],
+        ));
+    }
+
+    // a test, unlike the two above, is addressed by the dotted module path the
+    // test runner imports it by, so this half does need the module resolver
+    if let Some(module) = file_to_module(db, file) {
+        lenses.extend(test_lenses(db, file, &module.name(db).to_string()));
+    }
+
+    lenses
+}
+
+/// the lenses above every test class and test method of `file`
+fn test_lenses(db: &dyn Db, file: File, module: &str) -> Vec<DjangoCodeLens> {
+    // a test class reaches `unittest.TestCase` through its bases, and every base
+    // it is followed through has to be resolved. a file that declares no class at
+    // all is the common case and costs a parse this query has already paid for
+    let parsed = parsed_module(db, file).load(db);
+
+    let mut lenses = Vec::new();
+
+    for class in parsed.suite().iter().filter_map(class_def) {
+        if !is_test_class(db, file, class) {
+            continue;
+        }
+
+        let dotted = format!("{module}.{}", class.name);
+        lenses.push(DjangoCodeLens {
+            range: class.name.range(),
+            title: format!("run {}", class.name),
+            action: DjangoLensAction::Run(arguments(["test", &dotted])),
+        });
+
+        for method in class.body.iter().filter_map(function_def) {
+            if !method.name.starts_with(TEST_METHOD_PREFIX) {
+                continue;
+            }
+
+            lenses.push(DjangoCodeLens {
+                range: method.name.range(),
+                title: "run test".to_string(),
+                action: DjangoLensAction::Run(arguments([
+                    "test",
+                    &format!("{dotted}.{}", method.name),
+                ])),
+            });
+        }
+    }
+
+    lenses
+}
+
+/// a file-level lens that runs `manage.py`
+fn runnable<S: AsRef<str>>(
+    title: String,
+    arguments: impl IntoIterator<Item = S>,
+) -> DjangoCodeLens {
+    DjangoCodeLens {
+        range: FILE_HEADER,
+        title,
+        action: DjangoLensAction::Run(self::arguments(arguments)),
+    }
+}
+
+fn arguments<S: AsRef<str>>(arguments: impl IntoIterator<Item = S>) -> Vec<CompactString> {
+    arguments
+        .into_iter()
+        .map(|argument| argument.as_ref().to_compact_string())
+        .collect()
+}
+
+fn class_def(stmt: &Stmt) -> Option<&ast::StmtClassDef> {
+    match stmt {
+        Stmt::ClassDef(class) => Some(class),
+        _ => None,
+    }
+}
+
+fn function_def(stmt: &Stmt) -> Option<&ast::StmtFunctionDef> {
+    match stmt {
+        Stmt::FunctionDef(function) => Some(function),
+        _ => None,
+    }
+}
+
+/// the app label the file at `path` belongs to, and what it is called below `at`
+///
+/// django labels an app by the last component of its package, so a
+/// `myproject/apps/blog/migrations/0001_initial.py` is the `blog` app's, and the
+/// migration it names is `0001_initial`. the split component may be a directory
+/// or the file's own stem, which is what lets one function answer both for an
+/// app's `migrations` package and for its `models` module — and a file that *is*
+/// the split component names nothing below it.
+fn split_path<'a>(path: &'a SystemPath, at: &str) -> Option<(&'a str, Option<&'a str>)> {
+    let stem = path.file_stem()?;
+    let directory = path.parent()?;
+
+    // the file *is* the split, as an app's `models.py` is
+    if stem == at {
+        // a root, or a windows drive prefix, names no app
+        return Some((directory.file_name()?, None));
+    }
+
+    // the file is directly inside the split, as an app's migrations are. anything
+    // further down is in some directory of its own that django does not load
+    if directory.file_name() == Some(at) {
+        return Some((
+            directory.parent()?.file_name()?,
+            // django's own `__init__` is the package, not a member of it
+            (stem != "__init__").then_some(stem),
+        ));
+    }
+
+    None
+}
+
+#[cfg(test)]
+mod tests {
+    use super::{SystemPath, split_path};
+    use crate::django_template::tests::TemplateTest;
+
+    /// the mock django a lens test is written against
+    ///
+    /// `TestCase` descends from `unittest`'s, which is what a test class is
+    /// recognised by, and `Model` is what makes a `models.py` worth a
+    /// `makemigrations`.
+    const DJANGO: &[(&str, &str)] = &[
+        ("django/__init__.py", ""),
+        ("django/db/__init__.py", ""),
+        ("django/db/models/__init__.py", "class Model: ...\n"),
+        (
+            "django/test/__init__.py",
+            "
+            import unittest
+
+            class SimpleTestCase(unittest.TestCase): ...
+
+            class TestCase(SimpleTestCase): ...
+            ",
+        ),
+    ];
+
+    /// the entry point and settings every runnable is gated on
+    const PROJECT: &[(&str, &str)] = &[
+        (
+            "manage.py",
+            "
+            import os
+
+            os.environ.setdefault('DJANGO_SETTINGS_MODULE', 'project.settings')
+            ",
+        ),
+        ("project/__init__.py", ""),
+        (
+            "project/settings.py",
+            "
+            INSTALLED_APPS = ['blog']
+
+            TEMPLATES = [{'DIRS': [], 'APP_DIRS': True, 'OPTIONS': {}}]
+            ",
+        ),
+        ("blog/__init__.py", ""),
+    ];
+
+    /// a whole django project, with `sources` written last so the file under test
+    /// is one of them
+    fn project(sources: &[(&str, &str)]) -> TemplateTest {
+        let mut all: Vec<(&str, &str)> = DJANGO.to_vec();
+        all.extend_from_slice(PROJECT);
+        all.extend_from_slice(sources);
+
+        TemplateTest::new(&all)
+    }
+
+    /// the same, with no `manage.py` for a runnable to be run through
+    fn without_entry_point(sources: &[(&str, &str)]) -> TemplateTest {
+        let mut all: Vec<(&str, &str)> = DJANGO.to_vec();
+        all.extend(
+            PROJECT
+                .iter()
+                .filter(|(path, _)| *path != "manage.py")
+                .copied(),
+        );
+        all.extend_from_slice(sources);
+
+        TemplateTest::new(&all)
+    }
+
+    #[test]
+    fn a_template_names_the_view_that_renders_it() {
+        let test = project(&[
+            (
+                "blog/views.py",
+                "
+                from django.shortcuts import render
+
+                def post(request):
+                    return render(request, 'blog/post.html', {})
+                ",
+            ),
+            ("blog/templates/blog/post.html", "<p>a</p>\n"),
+        ]);
+
+        assert_eq!(
+            test.lenses(),
+            ["rendered by blog.views.post -> /blog/views.py:post"]
+        );
+    }
+
+    #[test]
+    fn a_template_several_views_render_names_every_one_of_them() {
+        let test = project(&[
+            (
+                "blog/views.py",
+                "
+                from django.shortcuts import render
+
+                def post(request):
+                    return render(request, 'blog/post.html', {})
+
+                def preview(request):
+                    return render(request, 'blog/post.html', {})
+                ",
+            ),
+            (
+                "blog/admin_views.py",
+                "
+                from django.shortcuts import render
+
+                def moderate(request):
+                    return render(request, 'blog/post.html', {})
+                ",
+            ),
+            ("blog/templates/blog/post.html", "<p>a</p>\n"),
+        ]);
+
+        assert_eq!(
+            test.lenses(),
+            [
+                "rendered by blog.admin_views.moderate, blog.views.post, blog.views.preview \
+                 -> /blog/admin_views.py:moderate, /blog/views.py:post, /blog/views.py:preview"
+            ]
+        );
+    }
+
+    #[test]
+    fn a_class_based_view_is_named_by_its_class() {
+        let test = project(&[
+            (
+                "blog/views.py",
+                "
+                from django.views.generic import DetailView
+
+                class BookDetail(DetailView):
+                    template_name = 'blog/detail.html'
+                ",
+            ),
+            ("blog/templates/blog/detail.html", "<p>a</p>\n"),
+        ]);
+
+        assert_eq!(
+            test.lenses(),
+            ["rendered by blog.views.BookDetail -> /blog/views.py:BookDetail"]
+        );
+    }
+
+    #[test]
+    fn a_template_nothing_renders_gets_no_lens_rather_than_an_empty_one() {
+        let test = project(&[
+            ("blog/views.py", "from django.shortcuts import render\n"),
+            ("blog/templates/blog/orphan.html", "<p>a</p>\n"),
+        ]);
+
+        assert!(test.lenses().is_empty(), "got {:?}", test.lenses());
+    }
+
+    #[test]
+    fn a_test_class_and_each_of_its_test_methods_are_runnable() {
+        let test = project(&[(
+            "blog/tests.py",
+            "
+            from django.test import TestCase
+
+            class BookTest(TestCase):
+                def setUp(self): ...
+
+                def test_detail(self): ...
+
+                def test_listing(self): ...
+            ",
+        )]);
+
+        assert_eq!(
+            test.lenses(),
+            [
+                "run BookTest -> manage.py test blog.tests.BookTest",
+                "run test -> manage.py test blog.tests.BookTest.test_detail",
+                "run test -> manage.py test blog.tests.BookTest.test_listing",
+            ]
+        );
+    }
+
+    #[test]
+    fn a_test_class_is_recognised_through_a_base_of_the_projects_own() {
+        let test = project(&[
+            (
+                "blog/base_tests.py",
+                "
+                from django.test import TestCase
+
+                class SiteTest(TestCase): ...
+                ",
+            ),
+            (
+                "blog/tests.py",
+                "
+                from blog.base_tests import SiteTest
+
+                class BookTest(SiteTest):
+                    def test_detail(self): ...
+                ",
+            ),
+        ]);
+
+        assert_eq!(
+            test.lenses(),
+            [
+                "run BookTest -> manage.py test blog.tests.BookTest",
+                "run test -> manage.py test blog.tests.BookTest.test_detail",
+            ]
+        );
+    }
+
+    #[test]
+    fn a_project_with_no_entry_point_offers_no_runnable() {
+        let test = without_entry_point(&[(
+            "blog/tests.py",
+            "
+            from django.test import TestCase
+
+            class BookTest(TestCase):
+                def test_detail(self): ...
+            ",
+        )]);
+
+        assert!(test.lenses().is_empty(), "got {:?}", test.lenses());
+    }
+
+    #[test]
+    fn an_ordinary_python_module_gets_no_lens_at_all() {
+        let test = project(&[(
+            "blog/views.py",
+            "
+            from django.shortcuts import render
+
+            class Helper:
+                def test_shaped_but_no_test(self): ...
+
+            def post(request):
+                return render(request, 'blog/post.html', {})
+            ",
+        )]);
+
+        assert!(test.lenses().is_empty(), "got {:?}", test.lenses());
+    }
+
+    #[test]
+    fn a_migration_is_runnable_both_ways() {
+        let test = project(&[
+            ("blog/migrations/__init__.py", ""),
+            ("blog/migrations/0001_initial.py", "operations = []\n"),
+        ]);
+
+        assert_eq!(
+            test.lenses(),
+            [
+                "migrate to 0001_initial -> manage.py migrate blog 0001_initial",
+                "show sql -> manage.py sqlmigrate blog 0001_initial",
+            ]
+        );
+    }
+
+    #[test]
+    fn the_package_a_migration_lives_in_is_not_itself_a_migration() {
+        let test = project(&[("blog/migrations/__init__.py", "")]);
+
+        assert!(test.lenses().is_empty(), "got {:?}", test.lenses());
+    }
+
+    #[test]
+    fn a_models_module_that_declares_a_model_can_make_migrations() {
+        let test = project(&[(
+            "blog/models.py",
+            "
+            from django.db import models
+
+            class Book(models.Model): ...
+            ",
+        )]);
+
+        assert_eq!(
+            test.lenses(),
+            ["make migrations for blog -> manage.py makemigrations blog"]
+        );
+    }
+
+    #[test]
+    fn a_models_module_that_declares_no_model_has_nothing_to_migrate() {
+        let test = project(&[("blog/models.py", "from django.db import models\n")]);
+
+        assert!(test.lenses().is_empty(), "got {:?}", test.lenses());
+    }
+
+    #[test]
+    fn a_migration_names_the_app_it_belongs_to() {
+        assert_eq!(
+            split_path(
+                SystemPath::new("/src/blog/migrations/0001_initial.py"),
+                "migrations"
+            ),
+            Some(("blog", Some("0001_initial")))
+        );
+    }
+
+    #[test]
+    fn an_app_nested_below_a_package_is_labelled_by_its_own_name() {
+        // django's `AppConfig.label` defaults to the last component, not the whole
+        // dotted path
+        assert_eq!(
+            split_path(SystemPath::new("/myproject/apps/blog/models.py"), "models"),
+            Some(("blog", None))
+        );
+    }
+
+    #[test]
+    fn a_module_of_a_models_package_still_belongs_to_the_app() {
+        assert_eq!(
+            split_path(SystemPath::new("/blog/models/book.py"), "models"),
+            Some(("blog", Some("book")))
+        );
+    }
+
+    #[test]
+    fn a_module_below_neither_splits_nowhere() {
+        assert_eq!(
+            split_path(SystemPath::new("/blog/views.py"), "migrations"),
+            None
+        );
+    }
+
+    #[test]
+    fn a_module_directly_under_the_root_belongs_to_no_app() {
+        assert_eq!(split_path(SystemPath::new("/models.py"), "models"), None);
+        assert_eq!(
+            split_path(SystemPath::new("/migrations/0001_initial.py"), "migrations"),
+            None
+        );
+    }
+
+    #[test]
+    fn a_migration_nested_further_down_is_no_migration() {
+        assert_eq!(
+            split_path(
+                SystemPath::new("/blog/migrations/old/0001_initial.py"),
+                "migrations"
+            ),
+            None
+        );
+    }
+}
diff --git a/crates/ty_ide/src/django_template/completion.rs b/crates/ty_ide/src/django_template/completion.rs
index c014ec5962..3b11d8ab39 100644
--- a/crates/ty_ide/src/django_template/completion.rs
+++ b/crates/ty_ide/src/django_template/completion.rs
@@ -20,11 +20,12 @@ use ty_project::Db;
 
 use crate::completion::CompletionKind;
 
-use super::builtins;
+use super::builtins::{self, Provided};
 use super::index::{Block, TemplateIndex};
 use super::lexer::{Construct, ConstructKind, Token, TokenKind, string_contents};
 use super::project::{self, LibrarySource, Registration, RegistrationKind};
 use super::resolve;
+use super::uses::URL_TAG;
 
 /// an edit a completion carries alongside the text it inserts
 #[derive(Debug, Clone, PartialEq, Eq)]
@@ -105,6 +106,7 @@ pub(crate) fn completions(
         Context::TemplatePath => template_paths(db, &cursor),
         Context::StaticPath => static_paths(db, &cursor),
         Context::UrlName => url_names(db, &cursor),
+        Context::RouteArgument(route) => route_arguments(db, file, index, offset, &cursor, &route),
         Context::Library => libraries(db, index, &cursor),
         Context::BlockName => block_names(db, file, index, &cursor),
         Context::PartialName => partial_names(db, file, index, &cursor),
@@ -130,6 +132,8 @@ enum Context {
     StaticPath,
     /// the route a `{% url %}` reverses
     UrlName,
+    /// an argument the named route takes, in a `{% url %}` that has named one
+    RouteArgument(CompactString),
     /// the library a `{% load %}` loads
     Library,
     /// the name a `{% block %}` overrides
@@ -201,18 +205,22 @@ impl<'a> Cursor<'a> {
             .is_some_and(|token| token.kind == TokenKind::String)
     }
 
-    /// the token before the cursor, skipping the one being typed
-    fn previous(&self) -> Option<&'a Token> {
-        let before = match self.current {
+    /// the index in `tokens` of the token being typed, or of the position the
+    /// cursor would insert one at
+    fn index(&self) -> usize {
+        match self.current {
             Some(index) => index,
             None => self
                 .tokens
                 .iter()
                 .position(|token| token.range.start() >= self.offset)
                 .unwrap_or(self.tokens.len()),
-        };
+        }
+    }
 
-        self.tokens.get(before.checked_sub(1)?)
+    /// the token before the cursor, skipping the one being typed
+    fn previous(&self) -> Option<&'a Token> {
+        self.tokens.get(self.index().checked_sub(1)?)
     }
 
     /// how many argument tokens the cursor is preceded by
@@ -221,16 +229,7 @@ impl<'a> Cursor<'a> {
     /// at position zero.
     fn argument_position(&self) -> usize {
         let tag_name = usize::from(self.construct.name.is_some());
-        let before = match self.current {
-            Some(index) => index,
-            None => self
-                .tokens
-                .iter()
-                .position(|token| token.range.start() >= self.offset)
-                .unwrap_or(self.tokens.len()),
-        };
-
-        before.saturating_sub(tag_name)
+        self.index().saturating_sub(tag_name)
     }
 
     /// whether the cursor is still on the tag's own name
@@ -258,7 +257,7 @@ impl<'a> Cursor<'a> {
             match (self.tag(), position) {
                 ("extends" | "include", 0) => return Context::TemplatePath,
                 ("static", 0) => return Context::StaticPath,
-                ("url", 0) => return Context::UrlName,
+                (URL_TAG, 0) => return Context::UrlName,
                 ("load", _) => return Context::Library,
                 ("block", 0) => return Context::BlockName,
                 ("partial", 0) => return Context::PartialName,
@@ -272,8 +271,88 @@ impl<'a> Cursor<'a> {
                 path if path.is_empty() => Context::None,
                 path => Context::Member(path),
             },
-            _ => Context::Variable,
+            _ => match self.route() {
+                Some(route) => Context::RouteArgument(route),
+                None => Context::Variable,
+            },
+        }
+    }
+
+    /// the route a `{% url %}` names, where the cursor is starting an argument
+    /// to it
+    ///
+    /// only a position that begins a fresh argument counts: what follows a
+    /// `name=` is that argument's value rather than another argument's name, and
+    /// what follows an `as` names the tag's result rather than its input. a
+    /// quoted position is a value too, since a route takes its arguments by bare
+    /// name.
+    fn route(&self) -> Option<CompactString> {
+        if self.construct.kind != ConstructKind::Tag
+            || self.tag() != URL_TAG
+            || self.argument_position() == 0
+            || self.in_string()
+        {
+            return None;
+        }
+
+        let before = self.tokens.get(..self.index())?;
+        if before.iter().any(|token| self.is_keyword(token, "as"))
+            || before
+                .last()
+                .is_some_and(|token| token.kind == TokenKind::Operator)
+        {
+            return None;
+        }
+
+        let name = before
+            .iter()
+            .find(|token| token.kind == TokenKind::String)?;
+        Some(self.source[string_contents(self.source, name.range)].to_compact_string())
+    }
+
+    /// the arguments a `{% url %}` already passes, as the names it gives and
+    /// whether it passes anything by position
+    ///
+    /// the token being typed is not one of them: a name half written is one the
+    /// user is still choosing.
+    fn arguments_given(&self) -> (FxHashSet<CompactString>, bool) {
+        let mut named = FxHashSet::default();
+        let mut positional = false;
+        // the tag's own name and the route it reverses come before its arguments
+        let start = usize::from(self.construct.name.is_some()) + 1;
+
+        for (index, token) in self.tokens.iter().enumerate().skip(start) {
+            if self.is_keyword(token, "as") {
+                break;
+            }
+            if Some(index) == self.current {
+                continue;
+            }
+
+            match token.kind {
+                TokenKind::KeywordArgument => {
+                    named.insert(self.source[token.range].to_compact_string());
+                }
+                // a value joined to what precedes it by an operator belongs to
+                // that argument rather than starting one of its own, which is
+                // what tells `pk=book.pk` from a positional `book.pk`
+                TokenKind::String
+                | TokenKind::Number
+                | TokenKind::Variable
+                | TokenKind::BuiltinConstant => {
+                    positional |= !self.tokens[..index]
+                        .last()
+                        .is_some_and(|previous| previous.kind == TokenKind::Operator);
+                }
+                _ => {}
+            }
         }
+
+        (named, positional)
+    }
+
+    fn is_keyword(&self, token: &Token, word: &str) -> bool {
+        token.kind == TokenKind::Keyword && self.source[token.range] == *word
     }
 
     /// the dotted path written immediately before the cursor's `.`
@@ -389,7 +468,13 @@ fn tag_names(
     let registrations = project::registrations(db, db.project());
 
     for tag in builtins::TAGS {
-        let library = djangos_library(registrations, tag.name, false).or(tag.library);
+        // a django that was read and does not register it is a django it is not
+        // in, and offering it would be offering a name django has no tag for
+        let Some(library) =
+            builtins::provided_by_django(db, tag.name, false).map(Provided::library)
+        else {
+            continue;
+        };
 
         let mut completion =
             TemplateCompletion::new(tag.name, CompletionKind::Keyword, cursor.range)
@@ -408,49 +493,39 @@ fn tag_names(
             continue;
         }
 
+        let library = needs_loading(registration);
         let mut completion = TemplateCompletion::new(
             registration.name.as_str(),
             CompletionKind::Keyword,
             cursor.range,
-        )
-        .detail(format!("{{% load {} %}}", registration.library));
+        );
+        if let Some(library) = library {
+            completion = completion.detail(format!("{{% load {library} %}}"));
+        }
         completion.documentation = registration
             .documentation
             .as_deref()
             .map(ToString::to_string);
-        completion.additional_edit = load_edit(Some(&registration.library));
+        completion.additional_edit = load_edit(library);
         completions.push(completion);
     }
 
     completions
 }
 
+/// the library a registration's template has to load first, where there is one
+///
+/// django's implicit builtins are a library like any other here, and a `{% load
+/// defaulttags %}` is not something anybody should be shown.
+fn needs_loading(registration: &Registration) -> Option<&str> {
+    (!registration.always_loaded).then(|| registration.library.as_str())
+}
+
 /// how an open block's tag reads, for a closing tag's detail line
 fn opening_tag(source: &str, block: &Block) -> String {
     source[block.open_range].trim().to_string()
 }
 
-/// the library the project's own django registers `name` under, when it does
-///
-/// the builtin table was written against one version of django, and a name can
-/// move between libraries or arrive in one from release to release. where the
-/// project's own django can be read, it is that django which decides. a tag the
-/// *project* happens to name after a builtin is not django's and says nothing.
-fn djangos_library<'a>(
-    registrations: &'a [Registration],
-    name: &str,
-    filter: bool,
-) -> Option<&'a str> {
-    registrations
-        .iter()
-        .find(|registration| {
-            registration.django
-                && registration.name == name
-                && (registration.kind == RegistrationKind::Filter) == filter
-        })
-        .map(|registration| registration.library.as_str())
-}
-
 /// whether the builtin table already offers this registration
 ///
 /// django's own libraries are discovered *and* tabulated, and the table's entry
@@ -475,7 +550,11 @@ fn filter_names(
     let registrations = project::registrations(db, db.project());
 
     for filter in builtins::FILTERS {
-        let library = djangos_library(registrations, filter.name, true).or(filter.library);
+        let Some(library) =
+            builtins::provided_by_django(db, filter.name, true).map(Provided::library)
+        else {
+            continue;
+        };
 
         let mut completion =
             TemplateCompletion::new(filter.name, CompletionKind::Function, cursor.range)
@@ -493,17 +572,20 @@ fn filter_names(
             continue;
         }
 
+        let library = needs_loading(registration);
         let mut completion = TemplateCompletion::new(
             registration.name.as_str(),
             CompletionKind::Function,
             cursor.range,
-        )
-        .detail(format!("{{% load {} %}}", registration.library));
+        );
+        if let Some(library) = library {
+            completion = completion.detail(format!("{{% load {library} %}}"));
+        }
         completion.documentation = registration
             .documentation
             .as_deref()
             .map(ToString::to_string);
-        completion.additional_edit = load_edit_for(index, &loaded, Some(&registration.library));
+        completion.additional_edit = load_edit_for(index, &loaded, library);
         completions.push(completion);
     }
 
@@ -621,20 +703,65 @@ fn url_names(db: &dyn Db, cursor: &Cursor<'_>) -> Vec<TemplateCompletion> {
         .collect()
 }
 
+/// the arguments the route a `{% url %}` names still takes
+///
+/// an argument can be passed by position as readily as by name, so the
+/// template's own variables are offered alongside the names rather than instead
+/// of them.
+fn route_arguments(
+    db: &dyn Db,
+    file: File,
+    index: &TemplateIndex,
+    offset: TextSize,
+    cursor: &Cursor<'_>,
+    route: &str,
+) -> Vec<TemplateCompletion> {
+    let mut completions = Vec::new();
+    let (named, positional) = cursor.arguments_given();
+
+    // django reverses by position or by name and refuses a mixture, so a tag
+    // that has already passed something positionally has no name left to take
+    if !positional {
+        for parameter in project::route_parameters(db, route) {
+            if named.contains(&parameter.name) {
+                continue;
+            }
+
+            let mut completion = TemplateCompletion::new(
+                parameter.name.as_str(),
+                CompletionKind::Field,
+                cursor.range,
+            );
+            completion.detail = parameter
+                .converter
+                .map(|converter| converter.name().to_string());
+            completion.insert = Some(format!("{}=", parameter.name));
+            completions.push(completion);
+        }
+    }
+
+    completions.extend(variables(db, file, index, offset, cursor));
+    completions
+}
+
 fn libraries(db: &dyn Db, index: &TemplateIndex, cursor: &Cursor<'_>) -> Vec<TemplateCompletion> {
     let loaded = loaded_libraries(db, index);
     let mut completions = Vec::new();
     let mut seen = FxHashSet::default();
 
-    for library in builtins::LIBRARIES {
-        if loaded.contains(&library.to_compact_string()) {
-            continue;
+    // the table's list is a fallback like the tables themselves: where django was
+    // read, the libraries it ships are discovered below and are the right list
+    if !project::django_is_authoritative(db, db.project()) {
+        for library in builtins::LIBRARIES {
+            if loaded.contains(&library.to_compact_string()) {
+                continue;
+            }
+            seen.insert(library.to_compact_string());
+            completions.push(
+                TemplateCompletion::new(*library, CompletionKind::Module, cursor.range)
+                    .detail("django"),
+            );
         }
-        seen.insert(library.to_compact_string());
-        completions.push(
-            TemplateCompletion::new(*library, CompletionKind::Module, cursor.range)
-                .detail("django"),
-        );
     }
 
     for library in project::tag_libraries(db, db.project()) {
@@ -784,7 +911,7 @@ pub(super) fn load_edit_for(
 #[cfg(test)]
 mod tests {
     use crate::django_template::django_template_completions;
-    use crate::django_template::tests::TemplateTest;
+    use crate::django_template::tests::{DJANGO_BUILTINS, TemplateTest};
 
     /// a small but complete django project: a couple of models, a view that
     /// renders a template with them, a url configuration, and a tag library
@@ -836,6 +963,8 @@ mod tests {
                 urlpatterns = [
                     path('books/<int:pk>/', detail, name='detail'),
                     path('books/', index, name='index'),
+                    path('books/<slug:slug>/<int:page>/', paged, name='paged'),
+                    re_path(r'^archive/(?P<year>[0-9]{4})/$', archive, name='archive'),
                 ]
                 ",
             ),
@@ -1209,7 +1338,12 @@ mod tests {
         let completions = project("{% url '<CURSOR>' %}").detailed();
         assert_eq!(
             completions,
-            ["blog:detail — books/<int:pk>/", "blog:index — books/"]
+            [
+                "blog:detail — books/<int:pk>/",
+                "blog:index — books/",
+                "blog:paged — books/<slug:slug>/<int:page>/",
+                "blog:archive — ^archive/(?P<year>[0-9]{4})/$"
+            ]
         );
     }
 
@@ -1251,6 +1385,131 @@ mod tests {
         );
     }
 
+    #[test]
+    fn url_offers_the_arguments_the_named_route_takes() {
+        let completions = project("{% url 'blog:detail' <CURSOR> %}").detailed();
+        assert_eq!(completions[0], "pk — int");
+    }
+
+    #[test]
+    fn a_route_argument_is_offered_with_the_equals_that_names_it() {
+        let test = project("{% url 'blog:detail' <CURSOR> %}");
+        let completions = django_template_completions(&test.db, test.file, test.offset);
+
+        assert_eq!(completions[0].insert.as_deref(), Some("pk="));
+    }
+
+    #[test]
+    fn url_offers_every_argument_a_route_takes() {
+        let completions = project("{% url 'blog:paged' <CURSOR> %}").detailed();
+        assert_eq!(&completions[..2], ["slug — slug", "page — int"]);
+    }
+
+    #[test]
+    fn url_does_not_offer_an_argument_already_given() {
+        let completions = project("{% url 'blog:paged' slug='a' <CURSOR> %}").detailed();
+        assert_eq!(completions[0], "page — int");
+    }
+
+    #[test]
+    fn url_offers_an_argument_the_cursor_is_rewriting() {
+        let completions = project("{% url 'blog:paged' sl<CURSOR> page=2 %}").detailed();
+        assert_eq!(completions[0], "slug — slug");
+    }
+
+    #[test]
+    fn url_offers_the_argument_of_a_re_path_route_without_a_converter() {
+        let completions = project("{% url 'blog:archive' <CURSOR> %}").detailed();
+        assert_eq!(completions[0], "year");
+    }
+
+    #[test]
+    fn url_offers_no_argument_for_a_route_that_takes_none() {
+        // the template's own variables are still offered: they are what a
+        // position accepts even where no argument is named
+        let completions = project("{% url 'blog:index' <CURSOR> %}").detailed();
+        assert!(
+            !completions
+                .iter()
+                .any(|completion| completion == "pk — int")
+        );
+        assert_eq!(completions.first().map(String::as_str), Some("book — Book"));
+    }
+
+    #[test]
+    fn url_offers_no_argument_for_a_route_that_is_not_there() {
+        let completions = project("{% url 'blog:missing' <CURSOR> %}").detailed();
+        assert_eq!(completions.first().map(String::as_str), Some("book — Book"));
+    }
+
+    #[test]
+    fn url_offers_no_argument_once_one_is_given_by_position() {
+        // django reverses by position or by name and refuses a mixture
+        let completions = project("{% url 'blog:paged' book.title <CURSOR> %}").detailed();
+        assert!(
+            !completions
+                .iter()
+                .any(|completion| completion == "page — int")
+        );
+    }
+
+    #[test]
+    fn url_offers_the_variables_a_positional_argument_could_be() {
+        let completions = project("{% url 'blog:detail' <CURSOR> %}").completions();
+        assert!(completions.contains(&"book".to_string()));
+    }
+
+    #[test]
+    fn url_offers_no_argument_where_a_value_goes() {
+        let completions = project("{% url 'blog:detail' pk=<CURSOR> %}").detailed();
+        assert_eq!(completions.first().map(String::as_str), Some("book — Book"));
+    }
+
+    #[test]
+    fn url_offers_no_argument_for_the_name_it_binds_its_result_to() {
+        let completions = project("{% url 'blog:detail' pk=1 as <CURSOR> %}").detailed();
+        assert!(
+            !completions
+                .iter()
+                .any(|completion| completion == "pk — int")
+        );
+    }
+
+    #[test]
+    fn url_offers_no_argument_inside_a_quoted_position() {
+        let completions = project("{% url 'blog:detail' '<CURSOR>' %}").detailed();
+        assert!(
+            !completions
+                .iter()
+                .any(|completion| completion == "pk — int")
+        );
+    }
+
+    #[test]
+    fn url_offers_the_arguments_of_every_route_that_shares_the_name() {
+        // django allows two routes one name and reverses against whichever of
+        // them matches, so what the name takes is the union of the two
+        let test = TemplateTest::new(&[
+            (
+                "blog/urls.py",
+                "
+                app_name = 'blog'
+
+                urlpatterns = [
+                    path('shelf/<int:pk>/', shelf, name='shelf'),
+                    path('shelf/<slug:slug>/', shelf, name='shelf'),
+                ]
+                ",
+            ),
+            (
+                "blog/templates/blog/post.html",
+                "{% url 'blog:shelf' <CURSOR> %}",
+            ),
+        ]);
+
+        assert_eq!(test.detailed(), ["pk — int", "slug — slug"]);
+    }
+
     #[test]
     fn static_offers_the_projects_assets() {
         let completions = project("{% load static %}{% static '<CURSOR>' %}").completions();
@@ -1504,4 +1763,87 @@ mod tests {
         .completions();
         assert!(completions.is_empty());
     }
+
+    /// a project whose django can be read all the way down to its implicit
+    /// builtins, which register something other than what the table says
+    fn with_djangos_own_builtins(template: &str) -> TemplateTest {
+        TemplateTest::with_site_packages(
+            &[
+                (
+                    "manage.py",
+                    "
+                    import os
+
+                    os.environ.setdefault('DJANGO_SETTINGS_MODULE', 'project.settings')
+                    ",
+                ),
+                ("project/__init__.py", ""),
+                (
+                    "project/settings.py",
+                    "
+                    INSTALLED_APPS = []
+
+                    TEMPLATES = [{'APP_DIRS': True}]
+                    ",
+                ),
+                ("app/templates/app/page.html", template),
+            ],
+            DJANGO_BUILTINS,
+        )
+    }
+
+    #[test]
+    fn a_tag_this_django_registers_that_the_table_never_heard_of_is_offered() {
+        let test = with_djangos_own_builtins("{% <CURSOR> %}");
+
+        assert!(
+            test.detailed().contains(&"squish".to_string()),
+            "django registers it into every template, so it is offered with no `{{% load %}}`"
+        );
+
+        let squish = django_template_completions(&test.db, test.file, test.offset)
+            .into_iter()
+            .find(|completion| completion.label == "squish")
+            .expect("the tag to be offered");
+        assert!(squish.additional_edit.is_none());
+        assert_eq!(squish.documentation.as_deref(), Some("squishes its body."));
+    }
+
+    #[test]
+    fn a_filter_this_django_registers_that_the_table_never_heard_of_is_offered() {
+        assert!(
+            with_djangos_own_builtins("{{ x|<CURSOR> }}")
+                .detailed()
+                .contains(&"shorten".to_string())
+        );
+    }
+
+    #[test]
+    fn a_name_the_table_has_that_this_django_does_not_register_is_not_offered() {
+        assert!(
+            !with_djangos_own_builtins("{% <CURSOR> %}")
+                .completions()
+                .contains(&"lorem".to_string()),
+            "the table's entry is not evidence about a django that has been read"
+        );
+        assert!(
+            !with_djangos_own_builtins("{{ x|<CURSOR> }}")
+                .completions()
+                .contains(&"slugify".to_string())
+        );
+    }
+
+    #[test]
+    fn the_table_is_offered_in_full_where_django_cannot_be_read() {
+        assert!(
+            project("{% <CURSOR> %}")
+                .completions()
+                .contains(&"lorem".to_string())
+        );
+        assert!(
+            project("{{ x|<CURSOR> }}")
+                .completions()
+                .contains(&"slugify".to_string())
+        );
+    }
 }
diff --git a/crates/ty_ide/src/django_template/diagnostics.rs b/crates/ty_ide/src/django_template/diagnostics.rs
index 297e225f28..0aa57674ed 100644
--- a/crates/ty_ide/src/django_template/diagnostics.rs
+++ b/crates/ty_ide/src/django_template/diagnostics.rs
@@ -36,16 +36,14 @@ use super::TEMPLATE_DIRECTORY;
 use super::completion::{load_edit_for, loaded_libraries};
 use super::index::{END_TAG_PREFIX, TemplateIndex};
 use super::lexer::{Construct, ConstructKind, Token, TokenKind, string_contents};
-use super::project::{self, RegistrationKind, UrlName};
+use super::project::{self, Parameter, RegistrationKind, UrlName};
 use super::resolve;
+use super::uses::URL_TAG;
 use super::{ancestors, builtins};
 
 /// the tag that names a static file
 const STATIC_TAG: &str = "static";
 
-/// the tag that reverses a route
-const URL_TAG: &str = "url";
-
 /// what everything a template says is checked against
 ///
 /// the indexes are read once here rather than once per check, since every one of
@@ -337,27 +335,10 @@ impl Checker<'_> {
 
     /// where a tag or filter comes from, as far as this template is concerned
     fn provider(&self, name: &str, filter: bool) -> Provider {
-        let registrations = project::registrations(self.db, self.db.project());
-
-        let table = if filter {
-            builtins::filter(name).map(|filter| filter.library)
-        } else {
-            builtins::tag(name).map(|tag| tag.library)
-        };
-
-        // the table's own answer is a fallback: which library django's own build
-        // registers a name in is read from the installed django where there is one
-        let django = registrations
-            .iter()
-            .find(|registration| {
-                registration.django
-                    && registration.name == name
-                    && (registration.kind == RegistrationKind::Filter) == filter
-            })
-            .map(|registration| Some(registration.library.as_str()));
-
-        if let Some(library) = django.or(table) {
-            return match library {
+        // what django provides is the installed django's to say where it can be
+        // read, and the builtin table's only where it cannot
+        if let Some(provided) = builtins::provided_by_django(self.db, name, filter) {
+            return match provided.library() {
                 None => Provider::Loaded,
                 Some(library) if self.loaded.contains(&library.to_compact_string()) => {
                     Provider::Loaded
@@ -366,6 +347,7 @@ impl Checker<'_> {
             };
         }
 
+        let registrations = project::registrations(self.db, self.db.project());
         let mut unloaded = None;
         for registration in registrations.iter().filter(|registration| {
             registration.name == name && (registration.kind == RegistrationKind::Filter) == filter
@@ -953,129 +935,6 @@ fn closes_a_block(db: &dyn Db, name: &str) -> bool {
         .is_some_and(|opening| opens_a_block(db, opening))
 }
 
-/// one argument a route pattern takes
-struct Parameter {
-    name: CompactString,
-    /// the converter django puts the argument through, where it is one of its own
-    converter: Option<Converter>,
-}
-
-/// the path converters django ships
-#[derive(Debug, Clone, Copy, PartialEq, Eq)]
-enum Converter {
-    Str,
-    Int,
-    Slug,
-    Uuid,
-    Path,
-}
-
-impl Converter {
-    fn of(name: &str) -> Option<Self> {
-        match name {
-            "str" => Some(Self::Str),
-            "int" => Some(Self::Int),
-            "slug" => Some(Self::Slug),
-            "uuid" => Some(Self::Uuid),
-            "path" => Some(Self::Path),
-            _ => None,
-        }
-    }
-
-    fn name(self) -> &'static str {
-        match self {
-            Self::Str => "str",
-            Self::Int => "int",
-            Self::Slug => "slug",
-            Self::Uuid => "uuid",
-            Self::Path => "path",
-        }
-    }
-
-    /// whether a value written out in the template is one this would match
-    fn matches(self, value: &str) -> bool {
-        match self {
-            Self::Str => !value.is_empty() && !value.contains('/'),
-            Self::Int => !value.is_empty() && value.bytes().all(|byte| byte.is_ascii_digit()),
-            Self::Slug => {
-                !value.is_empty()
-                    && value
-                        .bytes()
-                        .all(|byte| byte.is_ascii_alphanumeric() || byte == b'-' || byte == b'_')
-            }
-            Self::Uuid => {
-                let groups: Vec<&str> = value.split('-').collect();
-                groups.len() == 5
-                    && [8, 4, 4, 4, 12]
-                        == *groups.iter().map(|group| group.len()).collect::<Vec<_>>()
-                    && value
-                        .bytes()
-                        .all(|byte| byte.is_ascii_hexdigit() || byte == b'-')
-            }
-            Self::Path => !value.is_empty(),
-        }
-    }
-}
-
-impl UrlName {
-    /// the arguments this route takes, or `None` where they cannot be read
-    fn parameters(&self) -> Option<Vec<Parameter>> {
-        self.exact
-            .then_some(self.route.as_deref()?)
-            .and_then(parameters_of)
-    }
-}
-
-/// the arguments a route pattern names
-///
-/// django writes them two ways: `path()` takes `<converter:name>` and
-/// `re_path()` takes a named group. a pattern with an *unnamed* group takes
-/// arguments nothing can name, so it answers nothing rather than too few.
-fn parameters_of(pattern: &str) -> Option<Vec<Parameter>> {
-    let mut parameters = Vec::new();
-    let mut rest = pattern;
-
-    while let Some(index) = rest.find(['<', '(']) {
-        let after = &rest[index..];
-
-        if let Some(after) = after.strip_prefix('<') {
-            let (declaration, tail) = after.split_once('>')?;
-            let (converter, name) = match declaration.split_once(':') {
-                Some((converter, name)) => (Converter::of(converter), name),
-                None => (Some(Converter::Str), declaration),
-            };
-            parameters.push(Parameter {
-                name: name.to_compact_string(),
-                converter,
-            });
-            rest = tail;
-            continue;
-        }
-
-        let after = after.strip_prefix('(').unwrap_or(after);
-        if let Some(after) = after.strip_prefix("?P<") {
-            let (name, tail) = after.split_once('>')?;
-            parameters.push(Parameter {
-                name: name.to_compact_string(),
-                // what a regex group matches is not one of django's converters,
-                // so a literal written against it is not checked
-                converter: None,
-            });
-            rest = tail;
-            continue;
-        }
-
-        // a group that captures without naming takes a positional argument this
-        // has no name for, so the pattern is one to say nothing about
-        if !after.starts_with("?:") && !after.starts_with("?=") && !after.starts_with("?!") {
-            return None;
-        }
-        rest = after;
-    }
-
-    Some(parameters)
-}
-
 /// the `{# ty: ignore #}` comments a template writes
 ///
 /// a template has no `# type: ignore` to borrow, and its comment syntax is the
@@ -1184,7 +1043,7 @@ fn line_of(source: &str, offset: TextSize) -> OneIndexed {
 mod tests {
     use ruff_text_size::Ranged;
 
-    use crate::django_template::tests::TemplateTest;
+    use crate::django_template::tests::{DJANGO_BUILTINS, TemplateTest};
 
     /// a whole django project: a settings module the convention finds, an app
     /// with a tag library, models, a view, a url tree and a base template
@@ -1227,6 +1086,7 @@ mod tests {
                     "blog/models.py",
                     "
                     class Book:
+                        pk: int
                         title: str
 
                         def summary(self) -> str:
@@ -1257,6 +1117,10 @@ mod tests {
                         path('', index, name='index'),
                         path('<int:pk>/', detail, name='detail'),
                         path('<slug:slug>/<int:page>/', paged, name='paged'),
+                        path('<str:title>/', titled, name='titled'),
+                        path('<uuid:key>/', keyed, name='keyed'),
+                        path('<path:rest>/edit/', edit, name='edit'),
+                        re_path(r'^archive/(?P<year>[0-9]{4})/$', archive, name='archive'),
                     ]
                     ",
                 ),
@@ -1681,6 +1545,127 @@ mod tests {
         );
     }
 
+    /// the message every converter gives a literal it would refuse
+    ///
+    /// django's converters are regexes, and `reverse()` raises `NoReverseMatch`
+    /// for an argument that does not match one, so each of these is wrong before
+    /// the template is ever rendered.
+    #[test]
+    fn a_literal_no_converter_would_match_is_reported() {
+        let rejected = [
+            (
+                "blog:detail",
+                "pk='abc'",
+                "`pk` through `int`, which `abc` is not",
+            ),
+            (
+                "blog:detail",
+                "pk='-1'",
+                "`pk` through `int`, which `-1` is not",
+            ),
+            (
+                "blog:titled",
+                "title='a/b'",
+                "`title` through `str`, which `a/b` is not",
+            ),
+            (
+                "blog:paged",
+                "slug='a b' page=2",
+                "`slug` through `slug`, which `a b` is not",
+            ),
+            (
+                "blog:keyed",
+                "key='nope'",
+                "`key` through `uuid`, which `nope` is not",
+            ),
+            (
+                "blog:keyed",
+                "key='123E4567-E89B-12D3-A456-426614174000'",
+                "`key` through `uuid`, which `123E4567-E89B-12D3-A456-426614174000` is not",
+            ),
+            (
+                "blog:edit",
+                "rest=''",
+                "`rest` through `path`, which `` is not",
+            ),
+        ];
+
+        for (route, arguments, complaint) in rejected {
+            let template = format!("{{% url '{route}' {arguments} %}}\n");
+            assert_eq!(
+                project(&template).diagnostics(),
+                [format!(
+                    "invalid-route-arguments Error: `{route}` takes {complaint} \
+                     [{}]",
+                    template.trim_end()
+                )],
+                "{template}"
+            );
+        }
+    }
+
+    /// the same converters given a literal they do match
+    #[test]
+    fn a_literal_its_converter_matches_is_not_reported() {
+        let accepted = [
+            ("blog:detail", "pk=12"),
+            ("blog:detail", "pk='12'"),
+            ("blog:titled", "title='a b'"),
+            ("blog:paged", "slug='a-b_1' page=2"),
+            ("blog:keyed", "key='123e4567-e89b-12d3-a456-426614174000'"),
+            ("blog:edit", "rest='a/b/c'"),
+        ];
+
+        for (route, arguments) in accepted {
+            let template = format!("{{% url '{route}' {arguments} %}}\n");
+            assert_eq!(
+                project(&template).diagnostics(),
+                Vec::<String>::new(),
+                "{template}"
+            );
+        }
+    }
+
+    #[test]
+    fn a_literal_written_against_a_regex_group_is_not_reported() {
+        // a `re_path()` names its arguments but puts them through a pattern
+        // rather than a converter, so there is nothing here to hold one against
+        assert!(
+            project("{% url 'blog:archive' year='not a year' %}\n")
+                .diagnostics()
+                .is_empty()
+        );
+    }
+
+    #[test]
+    fn a_variable_argument_of_an_unknown_type_is_not_reported() {
+        assert!(
+            project("{% url 'blog:detail' pk=whatever %}\n")
+                .diagnostics()
+                .is_empty()
+        );
+    }
+
+    #[test]
+    fn a_variable_argument_of_a_type_the_converter_takes_is_not_reported() {
+        assert!(
+            project("{% url 'blog:detail' pk=book.pk %}{% url 'blog:detail' book.pk %}\n")
+                .diagnostics()
+                .is_empty()
+        );
+    }
+
+    #[test]
+    fn a_variable_argument_of_a_type_the_converter_would_not_take_is_not_reported() {
+        // django stringifies before it matches, so a `str` may still be all
+        // digits — a type alone is never enough to call an argument wrong
+        assert!(
+            project("{% url 'blog:detail' pk=book.title %}\n")
+                .diagnostics()
+                .is_empty()
+        );
+    }
+
     #[test]
     fn a_block_no_ancestor_declares_is_reported() {
         assert_eq!(
@@ -1832,4 +1817,67 @@ mod tests {
 
         assert!(test.diagnostics().is_empty());
     }
+
+    /// a project whose django can be read all the way down to its implicit
+    /// builtins
+    ///
+    /// what that django registers is deliberately not what the builtin table
+    /// says — see [`DJANGO_BUILTINS`] — which is the whole point: the table is a
+    /// fallback for a django nothing can read, not a claim about this one.
+    fn with_djangos_own_builtins(template: &str) -> TemplateTest {
+        TemplateTest::with_site_packages(
+            &[
+                (
+                    "manage.py",
+                    "
+                    import os
+
+                    os.environ.setdefault('DJANGO_SETTINGS_MODULE', 'project.settings')
+                    ",
+                ),
+                ("project/__init__.py", ""),
+                (
+                    "project/settings.py",
+                    "
+                    INSTALLED_APPS = []
+
+                    TEMPLATES = [{'DIRS': [], 'APP_DIRS': True, 'OPTIONS': {}}]
+                    ",
+                ),
+                ("app/templates/app/page.html", template),
+            ],
+            DJANGO_BUILTINS,
+        )
+    }
+
+    #[test]
+    fn a_tag_this_django_registers_that_the_table_never_heard_of_is_not_reported() {
+        assert_eq!(
+            with_djangos_own_builtins("{% squish %}{{ x|shorten:2 }}").diagnostics(),
+            Vec::<String>::new(),
+            "django registers them, so they are there whatever the table knows"
+        );
+    }
+
+    #[test]
+    fn a_name_the_table_has_that_this_django_does_not_register_is_reported() {
+        assert_eq!(
+            with_djangos_own_builtins("{% lorem %}").diagnostics(),
+            ["unknown-template-tag Error: no template tag named `lorem` [lorem]"]
+        );
+        assert_eq!(
+            with_djangos_own_builtins("{{ x|slugify }}").diagnostics(),
+            ["unknown-template-filter Error: no template filter named `slugify` [slugify]"]
+        );
+    }
+
+    #[test]
+    fn the_table_answers_in_full_where_django_cannot_be_read() {
+        // this project's mock django stops at `django.templatetags`, so nothing of
+        // what django itself registers was read and the table is all there is
+        assert_eq!(
+            project("{% lorem %}{{ book.title|slugify }}").diagnostics(),
+            Vec::<String>::new()
+        );
+    }
 }
diff --git a/crates/ty_ide/src/django_template/hover.rs b/crates/ty_ide/src/django_template/hover.rs
index 1029cb658a..fc11b32894 100644
--- a/crates/ty_ide/src/django_template/hover.rs
+++ b/crates/ty_ide/src/django_template/hover.rs
@@ -152,16 +152,20 @@ impl Site<'_> {
             text: written,
         };
 
-        let builtin = if filter {
-            builtins::filter(name).map(|filter| (filter.documentation, filter.library))
+        // the table documents django's tags and filters, but which of them this
+        // django has and where each comes from is that django's to say
+        let documented = if filter {
+            builtins::filter(name).map(|filter| filter.documentation)
         } else {
-            builtins::tag(name).map(|tag| (tag.documentation, tag.library))
+            builtins::tag(name).map(|tag| tag.documentation)
         };
 
-        if let Some((documented, library)) = builtin {
+        if let Some(documented) = documented
+            && let Some(provided) = builtins::provided_by_django(self.db, name, filter)
+        {
             return [header]
                 .into_iter()
-                .chain(documentation(documented, library))
+                .chain(documentation(documented, provided.library()))
                 .collect();
         }
 
diff --git a/crates/ty_ide/src/django_template/inlay_hints.rs b/crates/ty_ide/src/django_template/inlay_hints.rs
new file mode 100644
index 0000000000..6c98ccb43d
--- /dev/null
+++ b/crates/ty_ide/src/django_template/inlay_hints.rs
@@ -0,0 +1,263 @@
+//! inlay hints for django templates
+//!
+//! a template is short on nouns. `{% for book in shelf %}` never says what a
+//! `book` is, and `{% include "card.html" %}` never says which of the several
+//! `card.html`s in the project django will load — both are answers this module
+//! already computes for hover and goto, and an inlay hint is what puts them where
+//! the reader is looking rather than where the pointer is.
+
+use ruff_db::files::File;
+use ruff_text_size::{TextRange, TextSize};
+use ty_project::Db;
+
+use crate::InlayHintSettings;
+
+use super::index::{BindingOrigin, TemplateIndex, TemplateReference};
+use super::lexer::TokenKind;
+use super::project;
+use super::resolve;
+
+/// a hint written into a template between what the template itself says
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct TemplateInlayHint {
+    pub position: TextSize,
+    pub label: String,
+    pub kind: TemplateInlayHintKind,
+}
+
+/// what a template hint says
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum TemplateInlayHintKind {
+    /// the type of a name the template binds
+    Type,
+    /// the file a template name resolves to
+    Template,
+}
+
+/// every hint `range` of the template `file` shows
+pub(crate) fn inlay_hints(
+    db: &dyn Db,
+    file: File,
+    index: &TemplateIndex,
+    source: &str,
+    range: TextRange,
+    settings: &InlayHintSettings,
+) -> Vec<TemplateInlayHint> {
+    let mut hints = Vec::new();
+
+    if settings.template_binding_types {
+        binding_types(db, file, index, source, range, &mut hints);
+    }
+
+    if settings.resolved_templates {
+        for reference in index.extends().into_iter().chain(index.includes()) {
+            resolved_template(db, index, range, reference, &mut hints);
+        }
+    }
+
+    hints.sort_unstable_by_key(|hint| hint.position);
+    hints
+}
+
+/// the element type each `{% for %}` binding takes
+fn binding_types(
+    db: &dyn Db,
+    file: File,
+    index: &TemplateIndex,
+    source: &str,
+    range: TextRange,
+    hints: &mut Vec<TemplateInlayHint>,
+) {
+    for binding in index.bindings() {
+        if binding.origin != BindingOrigin::LoopVariable
+            || !range.contains_inclusive(binding.range.end())
+        {
+            continue;
+        }
+
+        // `{% for key, value in mapping.items %}` gives each target the *same*
+        // element type, because unpacking one element across several names is
+        // not something the resolution models. one wrong type written into the
+        // source is worse than the two the template already leaves unsaid
+        if index
+            .bindings()
+            .iter()
+            .filter(|candidate| {
+                candidate.origin == BindingOrigin::LoopVariable && candidate.scope == binding.scope
+            })
+            .count()
+            > 1
+        {
+            continue;
+        }
+
+        let Some(ty) = resolve::path_type(
+            db,
+            file,
+            index,
+            source,
+            binding.scope.start(),
+            &[&binding.name],
+        ) else {
+            continue;
+        };
+
+        hints.push(TemplateInlayHint {
+            position: binding.range.end(),
+            label: format!(": {}", ty.display(db)),
+            kind: TemplateInlayHintKind::Type,
+        });
+    }
+}
+
+/// the file an `{% extends %}` or an `{% include %}` name resolves to
+fn resolved_template(
+    db: &dyn Db,
+    index: &TemplateIndex,
+    range: TextRange,
+    reference: &TemplateReference,
+    hints: &mut Vec<TemplateInlayHint>,
+) {
+    // the reference's range is the literal's contents; the hint belongs after the
+    // literal itself, closing quote included
+    let Some(literal) = index.lexed().tokens().iter().find(|token| {
+        token.kind == TokenKind::String && token.range.contains_range(reference.range)
+    }) else {
+        return;
+    };
+
+    if !range.contains_inclusive(literal.range.end()) {
+        return;
+    }
+
+    let Some(target) = project::resolve_template(db, &reference.name) else {
+        return;
+    };
+    let Some(path) = path_label(db, target) else {
+        return;
+    };
+
+    hints.push(TemplateInlayHint {
+        position: literal.range.end(),
+        label: format!(" → {path}"),
+        kind: TemplateInlayHintKind::Template,
+    });
+}
+
+/// how a resolved template reads: its path within the project, since what the
+/// hint is for is telling two same-named templates in two apps apart
+fn path_label(db: &dyn Db, file: File) -> Option<String> {
+    let path = file.path(db).as_system_path()?;
+
+    Some(
+        path.strip_prefix(db.project().root(db))
+            .unwrap_or(path)
+            .as_str()
+            .to_string(),
+    )
+}
+
+#[cfg(test)]
+mod tests {
+    use crate::django_template::tests::TemplateTest;
+
+    /// a project whose view puts a list of books in a template's context
+    fn project(template: &str) -> TemplateTest {
+        TemplateTest::new(&[
+            (
+                "blog/models.py",
+                "
+                class Book:
+                    title: str
+                ",
+            ),
+            (
+                "blog/views.py",
+                "
+                from blog.models import Book
+
+                def post(request):
+                    return render(request, 'blog/post.html', {'shelf': [Book()]})
+                ",
+            ),
+            (
+                "blog/templates/blog/card.html",
+                "{% block card %}{% endblock %}",
+            ),
+            ("blog/templates/blog/post.html", template),
+        ])
+    }
+
+    #[test]
+    fn a_loop_over_a_known_iterable_shows_the_element_type() {
+        assert_eq!(
+            project("{% for book in shelf %}{{ book.title }}{% endfor %}").hints(),
+            ["Type at `book`: `: Book`"]
+        );
+    }
+
+    #[test]
+    fn a_loop_over_an_unknown_iterable_shows_nothing() {
+        assert_eq!(
+            project("{% for book in mystery %}{{ book }}{% endfor %}").hints(),
+            Vec::<String>::new()
+        );
+    }
+
+    #[test]
+    fn a_loop_that_unpacks_shows_nothing() {
+        assert_eq!(
+            project("{% for a, b in shelf %}{{ a }}{% endfor %}").hints(),
+            Vec::<String>::new(),
+            "one element type across two names would be wrong for both"
+        );
+    }
+
+    #[test]
+    fn an_include_shows_the_file_it_resolves_to() {
+        assert_eq!(
+            project("{% include 'blog/card.html' %}").hints(),
+            ["Template at `'blog/card.html'`: ` → blog/templates/blog/card.html`"]
+        );
+    }
+
+    #[test]
+    fn an_extends_shows_the_file_it_resolves_to() {
+        assert_eq!(
+            project("{% extends 'blog/card.html' %}").hints(),
+            ["Template at `'blog/card.html'`: ` → blog/templates/blog/card.html`"]
+        );
+    }
+
+    #[test]
+    fn an_include_that_resolves_to_nothing_shows_nothing() {
+        assert_eq!(
+            project("{% include 'blog/missing.html' %}").hints(),
+            Vec::<String>::new()
+        );
+    }
+
+    #[test]
+    fn a_hint_outside_the_requested_range_is_left_out() {
+        let test = project("{% include 'blog/card.html' %}\n{% for book in shelf %}{% endfor %}");
+
+        assert_eq!(
+            test.hints_in(0..31),
+            ["Template at `'blog/card.html'`: ` → blog/templates/blog/card.html`"]
+        );
+    }
+
+    #[test]
+    fn a_setting_that_is_off_shows_none_of_its_kind() {
+        let test = project("{% include 'blog/card.html' %}{% for book in shelf %}{% endfor %}");
+
+        assert_eq!(
+            test.hints_with(|settings| settings.template_binding_types = true),
+            ["Type at `book`: `: Book`"]
+        );
+        assert_eq!(
+            test.hints_with(|settings| settings.resolved_templates = true),
+            ["Template at `'blog/card.html'`: ` → blog/templates/blog/card.html`"]
+        );
+    }
+}
diff --git a/crates/ty_ide/src/django_template/project.rs b/crates/ty_ide/src/django_template/project.rs
index a89a34cefb..ccefafc01e 100644
--- a/crates/ty_ide/src/django_template/project.rs
+++ b/crates/ty_ide/src/django_template/project.rs
@@ -24,11 +24,11 @@ use ruff_python_ast::visitor::{Visitor, walk_expr, walk_stmt};
 use ruff_python_ast::{self as ast, AnyNodeRef, Expr, Stmt};
 use ruff_text_size::{Ranged, TextRange, TextSize};
 use rustc_hash::{FxHashMap, FxHashSet};
-use ty_module_resolver::{Module, ModuleName, resolve_module, resolve_real_module};
+use ty_module_resolver::{Module, ModuleName, file_to_module, resolve_module, resolve_real_module};
 use ty_project::{Db, Project};
 use ty_python_semantic::SemanticModel;
 use ty_python_semantic::types::ide_support::{
-    ImportAliasResolution, definitions_for_attribute, definitions_for_name,
+    ImportAliasResolution, ResolvedDefinition, definitions_for_attribute, definitions_for_name,
 };
 
 /// the directory name django's app-directories template loader looks in
@@ -46,6 +46,28 @@ const SETTINGS_MODULE_VARIABLE: &str = "DJANGO_SETTINGS_MODULE";
 /// the file stem of the script whose `DJANGO_SETTINGS_MODULE` is the one that counts
 const SETTINGS_ENTRY_POINT: &str = "manage";
 
+/// the package that declares the base every test case descends from
+const UNITTEST_PACKAGE: &str = "unittest";
+
+/// the base every test case descends from
+///
+/// django's own `SimpleTestCase` and everything below it are written against it,
+/// and django's test runner discovers by it, so it identifies a test class
+/// whether the class was written against django's bases or against plain
+/// `unittest`'s.
+const TEST_CASE_BASE: &str = "TestCase";
+
+/// the prefix django's test runner discovers test methods by
+///
+/// this is `unittest`'s own `testMethodPrefix`, which django does not change.
+pub(crate) const TEST_METHOD_PREFIX: &str = "test";
+
+/// the package a django app holds its migrations in
+pub(crate) const MIGRATIONS_PACKAGE: &str = "migrations";
+
+/// the module a django app declares its models in
+pub(crate) const MODELS_MODULE: &str = "models";
+
 /// the setting that configures the template engines
 const TEMPLATES_SETTING: &str = "TEMPLATES";
 
@@ -102,6 +124,17 @@ const MAX_VIEW_DEPTH: usize = 8;
 /// installed app's
 const DJANGO_PACKAGE: &str = "django";
 
+/// the modules every template engine starts with loaded
+///
+/// this is django's `Engine.default_builtins`, and it is where `{% for %}`,
+/// `{% extends %}` and `|upper` come from. they are libraries like any other
+/// here; the only difference is that nothing has to `{% load %}` them.
+const DEFAULT_BUILTIN_MODULES: &[&str] = &[
+    "django.template.defaulttags",
+    "django.template.defaultfilters",
+    "django.template.loader_tags",
+];
+
 /// the name a module's own path is bound to
 const FILE_NAME: &str = "__file__";
 
@@ -118,7 +151,10 @@ pub(crate) const TEMPLATE_NAME_ATTRIBUTE: &str = "template_name";
 pub(crate) const REVERSE_CALLEES: &[&str] = &["reverse", "reverse_lazy"];
 
 /// the keyword those functions take the route name by
-const REVERSE_NAME_KEYWORD: &str = "viewname";
+pub(crate) const REVERSE_NAME_KEYWORD: &str = "viewname";
+
+/// the keyword those functions take the route's own arguments by
+pub(crate) const REVERSE_ARGUMENTS_KEYWORD: &str = "kwargs";
 
 /// the keyword a rest framework hyperlinked field names its route by
 ///
@@ -202,6 +238,32 @@ const VIEWSET_QUERYSET_ATTRIBUTE: &str = "queryset";
 /// the manager attribute a queryset reaches its model through
 const MODEL_MANAGER_ATTRIBUTE: &str = "objects";
 
+/// django's own base class every model is written against
+const MODEL_BASE: &str = "Model";
+
+/// django's own base class every admin class is written against
+///
+/// an inline is deliberately not this: `TabularInline` and `StackedInline`
+/// descend from `InlineModelAdmin`, which is no `ModelAdmin`, and an inline is
+/// reached by another admin class's `inlines` rather than by a registration.
+const MODEL_ADMIN_BASE: &str = "ModelAdmin";
+
+/// the method an admin site registers a model with
+const ADMIN_REGISTER_METHOD: &str = "register";
+
+/// the keyword a registration names the admin class by
+const ADMIN_CLASS_KEYWORD: &str = "admin_class";
+
+/// the method a class-based view is handed to a route through
+const AS_VIEW_METHOD: &str = "as_view";
+
+/// how many base classes deep a class is followed towards django's own
+///
+/// a project's own hierarchy is a couple deep and django's own is another
+/// couple, so this is far past anything real — it is here so that a class that
+/// somehow inherits from itself stops the walk rather than running for ever.
+const MAX_BASE_DEPTH: usize = 16;
+
 /// how deep below the project root a `templates`/`static` directory is looked for
 ///
 /// django's own layout puts them at `<project>/<app>/templates`, and a
@@ -233,6 +295,8 @@ pub(crate) struct Registration {
     pub(crate) documentation: Option<Box<str>>,
     /// whether the library it comes from is django's own
     pub(crate) django: bool,
+    /// whether the library it comes from is loaded into every template already
+    pub(crate) always_loaded: bool,
 }
 
 /// where a tag library comes from
@@ -279,6 +343,173 @@ pub(crate) struct UrlName {
     /// a rest framework router generates its routes from a prefix rather than
     /// writing them out, so what one of them takes cannot be read off `route`.
     pub(crate) exact: bool,
+    /// the view the route hands the request to, where it names one this can read
+    pub(crate) view: Option<Target>,
+}
+
+/// what a python definition a django construct names is
+#[derive(Debug, Clone, Copy, PartialEq, Eq, get_size2::GetSize)]
+pub(crate) enum TargetKind {
+    Function,
+    Class,
+}
+
+/// a python definition a django construct names, wherever it is written
+#[derive(Debug, Clone, PartialEq, Eq, get_size2::GetSize)]
+pub(crate) struct Target {
+    pub(crate) name: CompactString,
+    pub(crate) kind: TargetKind,
+    pub(crate) file: File,
+    /// the name it is declared under, for navigation
+    pub(crate) range: TextRange,
+    /// the whole declaration
+    pub(crate) full_range: TextRange,
+}
+
+impl UrlName {
+    /// the arguments this route takes, or `None` where they cannot be read
+    pub(crate) fn parameters(&self) -> Option<Vec<Parameter>> {
+        self.exact
+            .then_some(self.route.as_deref()?)
+            .and_then(parameters_of)
+    }
+}
+
+/// one argument a route pattern takes
+pub(crate) struct Parameter {
+    pub(crate) name: CompactString,
+    /// the converter django puts the argument through, where it is one of its own
+    pub(crate) converter: Option<Converter>,
+}
+
+/// the path converters django ships
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub(crate) enum Converter {
+    Str,
+    Int,
+    Slug,
+    Uuid,
+    Path,
+}
+
+impl Converter {
+    fn of(name: &str) -> Option<Self> {
+        match name {
+            "str" => Some(Self::Str),
+            "int" => Some(Self::Int),
+            "slug" => Some(Self::Slug),
+            "uuid" => Some(Self::Uuid),
+            "path" => Some(Self::Path),
+            _ => None,
+        }
+    }
+
+    pub(crate) fn name(self) -> &'static str {
+        match self {
+            Self::Str => "str",
+            Self::Int => "int",
+            Self::Slug => "slug",
+            Self::Uuid => "uuid",
+            Self::Path => "path",
+        }
+    }
+
+    /// whether a value written out in the template is one this would match
+    pub(crate) fn matches(self, value: &str) -> bool {
+        match self {
+            Self::Str => !value.is_empty() && !value.contains('/'),
+            Self::Int => !value.is_empty() && value.bytes().all(|byte| byte.is_ascii_digit()),
+            Self::Slug => {
+                !value.is_empty()
+                    && value
+                        .bytes()
+                        .all(|byte| byte.is_ascii_alphanumeric() || byte == b'-' || byte == b'_')
+            }
+            Self::Uuid => {
+                let groups: Vec<&str> = value.split('-').collect();
+                groups.len() == 5
+                    && [8, 4, 4, 4, 12]
+                        == *groups.iter().map(|group| group.len()).collect::<Vec<_>>()
+                    // django's own pattern is lowercase, and `str(UUID(…))` is
+                    // the only spelling that reaches it at run time
+                    && value
+                        .bytes()
+                        .all(|byte| matches!(byte, b'0'..=b'9' | b'a'..=b'f' | b'-'))
+            }
+            Self::Path => !value.is_empty(),
+        }
+    }
+}
+
+/// the arguments a route pattern names
+///
+/// django writes them two ways: `path()` takes `<converter:name>` and
+/// `re_path()` takes a named group. a pattern with an *unnamed* group takes
+/// arguments nothing can name, so it answers nothing rather than too few.
+fn parameters_of(pattern: &str) -> Option<Vec<Parameter>> {
+    let mut parameters = Vec::new();
+    let mut rest = pattern;
+
+    while let Some(index) = rest.find(['<', '(']) {
+        let after = &rest[index..];
+
+        if let Some(after) = after.strip_prefix('<') {
+            let (declaration, tail) = after.split_once('>')?;
+            let (converter, name) = match declaration.split_once(':') {
+                Some((converter, name)) => (Converter::of(converter), name),
+                None => (Some(Converter::Str), declaration),
+            };
+            parameters.push(Parameter {
+                name: name.to_compact_string(),
+                converter,
+            });
+            rest = tail;
+            continue;
+        }
+
+        let after = after.strip_prefix('(').unwrap_or(after);
+        if let Some(after) = after.strip_prefix("?P<") {
+            let (name, tail) = after.split_once('>')?;
+            parameters.push(Parameter {
+                name: name.to_compact_string(),
+                // what a regex group matches is not one of django's converters,
+                // so a literal written against it is not checked
+                converter: None,
+            });
+            rest = tail;
+            continue;
+        }
+
+        // a group that captures without naming takes a positional argument this
+        // has no name for, so the pattern is one to say nothing about
+        if !after.starts_with("?:") && !after.starts_with("?=") && !after.starts_with("?!") {
+            return None;
+        }
+        rest = after;
+    }
+
+    Some(parameters)
+}
+
+/// the arguments every route of `name` takes, in the order they are declared
+///
+/// django allows two routes to share a name and reverses against whichever one
+/// matches, so the union is what such a name takes rather than either half.
+pub(crate) fn route_parameters(db: &dyn Db, name: &str) -> Vec<Parameter> {
+    let mut parameters: Vec<Parameter> = Vec::new();
+
+    for url in url_names(db, db.project())
+        .iter()
+        .filter(|url| url.name == name)
+    {
+        for parameter in url.parameters().into_iter().flatten() {
+            if !parameters.iter().any(|known| known.name == parameter.name) {
+                parameters.push(parameter);
+            }
+        }
+    }
+
+    parameters
 }
 
 /// where a name in a template's context comes from
@@ -320,9 +551,29 @@ pub(crate) struct ContextVariable {
 pub(crate) struct TemplateContext {
     /// the template the view names, as the loader sees it
     pub(crate) template: CompactString,
+    /// the view that renders it, where the name is written inside one
+    ///
+    /// a `render()` at module level is nobody's view, and a template rendered
+    /// only from there has none to name.
+    pub(crate) view: Option<ViewRef>,
     pub(crate) variables: Box<[ContextVariable]>,
 }
 
+/// the definition a template name is written inside
+#[derive(Debug, Clone, PartialEq, Eq, get_size2::GetSize)]
+pub(crate) struct ViewRef {
+    /// the definition's name, qualified by whatever it is nested in
+    ///
+    /// a view written inside another definition carries both names, since
+    /// `outer.inner` is what a reader is looking for and `inner` alone is not.
+    /// the module is deliberately not part of it: which module a file is comes
+    /// from the module resolver rather than from this scan.
+    pub(crate) path: CompactString,
+    pub(crate) file: File,
+    /// the innermost definition's own name, for navigation
+    pub(crate) range: TextRange,
+}
+
 /// a file inside one of the project's template directories
 #[derive(Debug, Clone, PartialEq, Eq, get_size2::GetSize)]
 pub(crate) struct DiscoveredFile {
@@ -421,6 +672,7 @@ pub(crate) fn registrations(db: &dyn Db, project: Project) -> Box<[Registration]
                 .iter()
                 .map(|registration| Registration {
                     django: library.source == LibrarySource::Django,
+                    always_loaded: library.always_loaded,
                     ..registration.clone()
                 })
         })
@@ -527,24 +779,27 @@ fn installed_libraries(db: &dyn Db, project: Project) -> Box<[Library]> {
         }
     }
 
+    // django's own implicit builtins, which no template has to load and which
+    // nothing above reaches: they live in `django.template`, not in anybody's
+    // `templatetags`. reading them is what stops the builtin table from being the
+    // last word on a django whose tags have moved on since it was written
+    for path in DEFAULT_BUILTIN_MODULES {
+        if let Some(discovered) = always_loaded_library(db, importing, path, LibrarySource::Django)
+        {
+            merge(&mut found, discovered);
+        }
+    }
+
     // a library the settings load into every template is available whether or not
     // any app installs it, and needs no `{% load %}` wherever it came from
     for path in &settings.always_loaded {
-        let Some(name) = ModuleName::new(path) else {
-            continue;
-        };
-        let Some(file) =
-            resolve_real_module(db, importing, &name).and_then(|module| module.file(db))
-        else {
-            continue;
-        };
-        let source = if name.components().next() == Some(DJANGO_PACKAGE) {
+        let source = if path.split('.').next() == Some(DJANGO_PACKAGE) {
             LibrarySource::Django
         } else {
             LibrarySource::Installed
         };
 
-        if let Some(discovered) = library(db, file, source, true) {
+        if let Some(discovered) = always_loaded_library(db, importing, path, source) {
             merge(&mut found, discovered);
         }
     }
@@ -552,6 +807,42 @@ fn installed_libraries(db: &dyn Db, project: Project) -> Box<[Library]> {
     found.into_boxed_slice()
 }
 
+/// the library a dotted module path names, as one no template has to `{% load %}`
+fn always_loaded_library(
+    db: &dyn Db,
+    importing: File,
+    path: &str,
+    source: LibrarySource,
+) -> Option<Library> {
+    let name = ModuleName::new(path)?;
+    let file = resolve_real_module(db, importing, &name)?.file(db)?;
+
+    library(db, file, source, true)
+}
+
+/// whether django's own registrations were read, and so are the last word on
+/// what django provides
+///
+/// the implicit builtins are the surest sign of a django this module can
+/// actually read: `Engine` imports all three itself, so a project where all
+/// three resolve is one whose django is really there. short of that, nothing of
+/// django's has been read at all and the builtin table stands on its own — which
+/// is the difference between a table that is a floor and a table that is a
+/// claim.
+#[salsa::tracked(returns(copy))]
+pub(crate) fn django_is_authoritative(db: &dyn Db, project: Project) -> bool {
+    let Some(importing) = *settings_file(db, project) else {
+        return false;
+    };
+
+    DEFAULT_BUILTIN_MODULES.iter().all(|path| {
+        ModuleName::new(path)
+            .and_then(|name| resolve_real_module(db, importing, &name))
+            .and_then(|module| module.file(db))
+            .is_some()
+    })
+}
+
 /// the package an `INSTALLED_APPS` entry names
 ///
 /// an entry names either the app's package (`"blog"`) or an `AppConfig` inside it
@@ -1438,6 +1729,7 @@ impl RegistrationVisitor {
             // one module is one library however it was reached, so where it came
             // from is [`registrations`]' to say rather than this scan's
             django: false,
+            always_loaded: false,
         })
     }
 }
@@ -1446,12 +1738,18 @@ impl<'ast> Visitor<'ast> for RegistrationVisitor {
     fn visit_stmt(&mut self, stmt: &'ast Stmt) {
         if let Stmt::FunctionDef(function) = stmt {
             let documentation = docstring_summary(&function.body);
-            // one function is one tag even if it somehow carries two registering
-            // decorators; the first is the one that names it
-            let registration = function.decorator_list.iter().find_map(|decorator| {
-                self.registration(decorator, &function.name, documentation.clone())
-            });
-            self.found.extend(registration);
+            // one function may be registered under several names: django's own
+            // `{% translate %}` and `{% trans %}` are one function carrying two
+            // `@register.tag` decorators, and taking only the first loses the
+            // older spelling entirely
+            let registrations: Vec<Registration> = function
+                .decorator_list
+                .iter()
+                .filter_map(|decorator| {
+                    self.registration(decorator, &function.name, documentation.clone())
+                })
+                .collect();
+            self.found.extend(registrations);
             return;
         }
 
@@ -1667,7 +1965,53 @@ fn django_settings(db: &dyn Db, project: Project) -> DjangoSettings {
 /// the one a developer runs.
 #[salsa::tracked]
 fn settings_file(db: &dyn Db, project: Project) -> Option<File> {
-    let mut naming: Vec<(File, CompactString)> = Vec::new();
+    let naming = settings_naming(db, project);
+
+    let naming = naming
+        .iter()
+        .find(|naming| is_entry_point(db, naming.file))
+        .or_else(|| naming.first())?;
+
+    resolve_module(db, naming.file, &ModuleName::new(&naming.module)?)?.file(db)
+}
+
+/// the project's `manage.py`, django's own entry point
+///
+/// this is the script `manage.py test`, `manage.py migrate` and the rest are run
+/// through, so a project without one is a project in which none of them can be
+/// run. it is identified the way [`settings_file`] identifies it — by naming
+/// `DJANGO_SETTINGS_MODULE` — since a script that doesn't is no django entry
+/// point whatever it happens to be called.
+#[salsa::tracked]
+pub(crate) fn manage_file(db: &dyn Db, project: Project) -> Option<File> {
+    settings_naming(db, project)
+        .iter()
+        .find(|naming| is_entry_point(db, naming.file))
+        .map(|naming| naming.file)
+}
+
+/// whether `file` is the script django's own `startproject` writes
+fn is_entry_point(db: &dyn Db, file: File) -> bool {
+    file.path(db)
+        .as_system_path()
+        .and_then(SystemPath::file_stem)
+        == Some(SETTINGS_ENTRY_POINT)
+}
+
+/// a file that points `DJANGO_SETTINGS_MODULE` somewhere, and where at
+#[derive(Debug, Clone, PartialEq, Eq, get_size2::GetSize)]
+struct SettingsNaming {
+    file: File,
+    module: CompactString,
+}
+
+/// every file of the project that names its settings module, in path order
+///
+/// the project's files come in no order worth relying on, and both consumers
+/// have to land on the same file twice running.
+#[salsa::tracked(returns(ref), heap_size=ruff_memory_usage::heap_size)]
+fn settings_naming(db: &dyn Db, project: Project) -> Box<[SettingsNaming]> {
+    let mut naming: Vec<SettingsNaming> = Vec::new();
 
     for file in &project.files(db) {
         // a stub sets no environment variable
@@ -1675,25 +2019,21 @@ fn settings_file(db: &dyn Db, project: Project) -> Option<File> {
             continue;
         }
         if let Some(module) = settings_module_in_file(db, file) {
-            naming.push((file, module.clone()));
+            naming.push(SettingsNaming {
+                file,
+                module: module.clone(),
+            });
         }
     }
 
-    // the project's files come in no order worth relying on, and the fallback has
-    // to land on the same file twice running
-    naming.sort_by(|(left, _), (right, _)| left.path(db).as_str().cmp(right.path(db).as_str()));
-
-    let (importing, module) = naming
-        .iter()
-        .find(|(file, _)| {
-            file.path(db)
-                .as_system_path()
-                .and_then(SystemPath::file_stem)
-                == Some(SETTINGS_ENTRY_POINT)
-        })
-        .or_else(|| naming.first())?;
+    naming.sort_by(|left, right| {
+        left.file
+            .path(db)
+            .as_str()
+            .cmp(right.file.path(db).as_str())
+    });
 
-    resolve_module(db, *importing, &ModuleName::new(module)?)?.file(db)
+    naming.into_boxed_slice()
 }
 
 /// the settings module `file` points `DJANGO_SETTINGS_MODULE` at
@@ -2081,25 +2421,11 @@ struct UrlVisitor<'db> {
 }
 
 impl UrlVisitor<'_> {
-    /// record `name` as a route of the list `binding`
-    fn record(
-        &mut self,
-        binding: Option<CompactString>,
-        name: &str,
-        file: File,
-        range: TextRange,
-        route: Option<CompactString>,
-        exact: bool,
-    ) {
+    /// record `route` as a route of the list `binding`
+    fn record(&mut self, binding: Option<CompactString>, route: UrlName) {
         self.found.push(UrlEntry {
             binding,
-            kind: UrlEntryKind::Route(UrlName {
-                name: name.to_compact_string(),
-                file,
-                range,
-                route: route.map(|route| route.as_str().into()),
-                exact,
-            }),
+            kind: UrlEntryKind::Route(route),
         });
     }
 
@@ -2173,11 +2499,14 @@ impl UrlVisitor<'_> {
 
         self.record(
             Some(binding.to_compact_string()),
-            &name,
-            self.file,
-            call.func.range(),
-            None,
-            false,
+            UrlName {
+                name,
+                file: self.file,
+                range: call.func.range(),
+                route: None,
+                exact: false,
+                view: None,
+            },
         );
     }
 
@@ -2197,13 +2526,21 @@ impl UrlVisitor<'_> {
         };
 
         let route = join_routes(self.prefix.as_deref(), route_of(call).as_deref());
+        let view = call
+            .arguments
+            .args
+            .get(1)
+            .and_then(|view| resolved_target(self.db, self.file, view_callable(view)));
         self.record(
             self.binding.clone(),
-            &name,
-            self.file,
-            keyword.value.range(),
-            route,
-            true,
+            UrlName {
+                name,
+                file: self.file,
+                range: keyword.value.range(),
+                route: route.map(|route| route.as_str().into()),
+                exact: true,
+                view,
+            },
         );
     }
 
@@ -2275,15 +2612,21 @@ impl UrlVisitor<'_> {
         // a router writes its own patterns from the prefix rather than taking
         // them, so the prefix is what a route reads as but not what it takes
         let route = join_routes(self.prefix.as_deref(), Some(prefix.as_str()));
+        let view = resolved_target(self.db, self.file, viewset);
+        let generated = |name: String, file: File, range: TextRange| UrlName {
+            name: name.to_compact_string(),
+            file,
+            range,
+            route: route.clone().map(|route| route.as_str().into()),
+            // a router writes its own patterns rather than taking them
+            exact: false,
+            view: view.clone(),
+        };
 
         for suffix in ROUTER_ROUTE_SUFFIXES {
             self.record(
                 binding.clone(),
-                &format!("{basename}-{suffix}"),
-                self.file,
-                anchor,
-                route.clone(),
-                false,
+                generated(format!("{basename}-{suffix}"), self.file, anchor),
             );
         }
 
@@ -2291,11 +2634,11 @@ impl UrlVisitor<'_> {
             // an action's route is that method's, so that is where it leads
             self.record(
                 binding.clone(),
-                &format!("{basename}-{}", action.url_name),
-                action.file,
-                action.range,
-                route.clone(),
-                false,
+                generated(
+                    format!("{basename}-{}", action.url_name),
+                    action.file,
+                    action.range,
+                ),
             );
         }
     }
@@ -2322,9 +2665,23 @@ fn resolved_class<T>(
     expr: &Expr,
     mut read: impl FnMut(File, &ast::StmtClassDef) -> T,
 ) -> Option<T> {
+    definitions_of(db, file, expr)
+        .into_iter()
+        .find_map(|resolved| {
+            let definition = resolved.definition()?;
+            let defining = definition.file(db);
+            let parsed = parsed_module(db, defining).load(db);
+            let class = definition.kind(db).as_class()?.node(&parsed);
+
+            Some(read(defining, class))
+        })
+}
+
+/// every definition `expr` resolves to, import aliases followed to their source
+fn definitions_of<'db>(db: &'db dyn Db, file: File, expr: &Expr) -> Vec<ResolvedDefinition<'db>> {
     let model = SemanticModel::new(db, file);
 
-    let definitions = match expr {
+    match expr {
         Expr::Name(name) => definitions_for_name(
             &model,
             name.id.as_str(),
@@ -2332,17 +2689,54 @@ fn resolved_class<T>(
             ImportAliasResolution::ResolveAliases,
         ),
         Expr::Attribute(attribute) => definitions_for_attribute(&model, attribute),
-        _ => return None,
-    };
+        _ => Vec::new(),
+    }
+}
 
-    definitions.into_iter().find_map(|resolved| {
-        let definition = resolved.definition()?;
-        let defining = definition.file(db);
-        let parsed = parsed_module(db, defining).load(db);
-        let class = definition.kind(db).as_class()?.node(&parsed);
+/// the class or function `expr` names, wherever it is declared
+fn resolved_target(db: &dyn Db, file: File, expr: &Expr) -> Option<Target> {
+    definitions_of(db, file, expr)
+        .into_iter()
+        .find_map(|resolved| {
+            let definition = resolved.definition()?;
+            let defining = definition.file(db);
+            let parsed = parsed_module(db, defining).load(db);
 
-        Some(read(defining, class))
-    })
+            let (name, kind, full_range) = match definition.kind(db) {
+                kind if kind.as_class().is_some() => {
+                    let class = kind.as_class()?.node(&parsed);
+                    (&class.name, TargetKind::Class, class.range())
+                }
+                kind => {
+                    let function = kind.as_function()?.node(&parsed);
+                    (&function.name, TargetKind::Function, function.range())
+                }
+            };
+
+            Some(Target {
+                name: name.id.to_compact_string(),
+                kind,
+                file: defining,
+                range: name.range(),
+                full_range,
+            })
+        })
+}
+
+/// what a route's view argument points at
+///
+/// a class-based view is written into a route through `as_view()`, and what the
+/// route reaches is the class that method belongs to.
+fn view_callable(expr: &Expr) -> &Expr {
+    match expr {
+        Expr::Call(call) => match &*call.func {
+            Expr::Attribute(attribute) if attribute.attr.as_str() == AS_VIEW_METHOD => {
+                &attribute.value
+            }
+            _ => expr,
+        },
+        _ => expr,
+    }
 }
 
 /// whether a router serves an index of what is registered with it
@@ -2631,14 +3025,34 @@ struct ContextVisitor<'db, 'ast> {
     db: &'db dyn Db,
     file: File,
     found: Vec<TemplateContext>,
-    /// the function bodies being walked, innermost last
+    /// the functions being walked, innermost last
     ///
     /// a context handed to `render()` by name is built by the statements of the
-    /// function that binds it, so that body is what the name is followed in.
-    scopes: Vec<&'ast [Stmt]>,
+    /// function that binds it, so that body is what the name is followed in —
+    /// and the same function is the view a lens names.
+    scopes: Vec<&'ast ast::StmtFunctionDef>,
 }
 
 impl<'ast> ContextVisitor<'_, 'ast> {
+    /// the view a render call found here is written in
+    fn enclosing_view(&self) -> Option<ViewRef> {
+        let innermost = self.scopes.last()?;
+
+        let mut path = CompactString::default();
+        for function in &self.scopes {
+            if !path.is_empty() {
+                path.push('.');
+            }
+            path.push_str(function.name.as_str());
+        }
+
+        Some(ViewRef {
+            path,
+            file: self.file,
+            range: innermost.name.range(),
+        })
+    }
+
     /// the context a `render()`/`TemplateResponse()` call passes
     ///
     /// both take the request first, the template second and the context third,
@@ -2666,11 +3080,12 @@ impl<'ast> ContextVisitor<'_, 'ast> {
 
         Some(TemplateContext {
             template,
+            view: self.enclosing_view(),
             variables: context
                 .map(|context| {
                     context_variables(
                         self.file,
-                        self.scopes.last().copied(),
+                        self.scopes.last().map(|function| function.body.as_slice()),
                         context,
                         MAX_CONTEXT_DEPTH,
                     )
@@ -2705,6 +3120,11 @@ impl<'ast> ContextVisitor<'_, 'ast> {
 
         Some(TemplateContext {
             template,
+            view: Some(ViewRef {
+                path: class.name.id.to_compact_string(),
+                file: self.file,
+                range: class.name.range(),
+            }),
             variables: variables.into_boxed_slice(),
         })
     }
@@ -2715,7 +3135,7 @@ impl<'ast> Visitor<'ast> for ContextVisitor<'_, 'ast> {
         match stmt {
             Stmt::ClassDef(class) => self.found.extend(self.class_based_view(class)),
             Stmt::FunctionDef(function) => {
-                self.scopes.push(&function.body);
+                self.scopes.push(function);
                 walk_stmt(self, stmt);
                 self.scopes.pop();
             }
@@ -3129,6 +3549,446 @@ fn processor_variables(db: &dyn Db, importing: File, name: &str) -> Vec<ContextV
     found
 }
 
+/// what django does with a class the project declares
+#[derive(Debug, Clone, Copy, PartialEq, Eq, get_size2::GetSize)]
+pub(crate) enum DjangoClassKind {
+    /// a subclass of django's `Model`, which is a table
+    Model,
+    /// a subclass of django's `ModelAdmin`, which is a model's admin page
+    Admin,
+}
+
+/// where a class is declared, which is what identifies it across files
+///
+/// its name is not enough — two apps may each hold a `BookAdmin` — and the
+/// class name's own range is unique within the file that declares it.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, get_size2::GetSize)]
+pub(crate) struct ClassRef {
+    pub(crate) file: File,
+    pub(crate) range: TextRange,
+}
+
+/// a class django gives a role to
+#[derive(Debug, Clone, PartialEq, Eq, get_size2::GetSize)]
+pub(crate) struct DjangoClass {
+    pub(crate) name: CompactString,
+    pub(crate) kind: DjangoClassKind,
+    pub(crate) file: File,
+    /// the class name, for navigation
+    pub(crate) range: TextRange,
+    /// the whole `class …:` statement
+    pub(crate) full_range: TextRange,
+    /// the classes it is written against, wherever they are declared
+    ///
+    /// this is what tells a base others are built on from a leaf nothing uses.
+    pub(crate) bases: Box<[ClassRef]>,
+}
+
+/// every model and admin class the project declares
+///
+/// unlike the scans above, this one is not gated on the source spelling any
+/// particular name: a model need not write django's own base itself, only
+/// inherit from something that eventually does, so there is no identifier such a
+/// class has to hold. what keeps it affordable is that a class with no bases
+/// costs nothing at all, and that each file's bases are followed once, in a
+/// query salsa keeps.
+#[salsa::tracked(returns(ref), heap_size=ruff_memory_usage::heap_size)]
+pub(crate) fn django_classes(db: &dyn Db, project: Project) -> Box<[DjangoClass]> {
+    project_scan(db, project, |db, file| {
+        django_classes_in_file(db, file).iter().cloned()
+    })
+}
+
+/// the models and admin classes one module declares
+#[salsa::tracked(returns(ref), heap_size=ruff_memory_usage::heap_size)]
+pub(crate) fn django_classes_in_file(db: &dyn Db, file: File) -> Box<[DjangoClass]> {
+    // a class only classifies by reaching a base django itself declares, and a
+    // module of django's is reached through an import that spells the package.
+    // so a project no file of which writes it has no such class anywhere, and
+    // this is what keeps a project that is no django project from having its
+    // every class followed up its bases
+    if !project_uses_django(db, db.project()) {
+        return Box::default();
+    }
+
+    let parsed = parsed_module(db, file).load(db);
+    let mut visitor = DjangoClassVisitor {
+        db,
+        file,
+        found: Vec::new(),
+    };
+    visitor.visit_body(parsed.suite());
+
+    visitor.found.into_boxed_slice()
+}
+
+struct DjangoClassVisitor<'db> {
+    db: &'db dyn Db,
+    file: File,
+    found: Vec<DjangoClass>,
+}
+
+impl<'ast> Visitor<'ast> for DjangoClassVisitor<'_> {
+    fn visit_stmt(&mut self, stmt: &'ast Stmt) {
+        if let Stmt::ClassDef(class) = stmt
+            && let Some(kind) = django_class_kind(self.db, self.file, class, MAX_BASE_DEPTH)
+        {
+            self.found.push(DjangoClass {
+                name: class.name.id.to_compact_string(),
+                kind,
+                file: self.file,
+                range: class.name.range(),
+                full_range: class.range(),
+                bases: class
+                    .bases()
+                    .iter()
+                    .filter_map(|base| class_ref(self.db, self.file, base))
+                    .collect(),
+            });
+        }
+
+        walk_stmt(self, stmt);
+    }
+}
+
+/// whether anything in the project so much as names django
+///
+/// the two halves are separate queries so that an edit to one module re-reads
+/// that module's source and no other, and so that the answer — which changes
+/// about once in a project's life — is backdated rather than invalidating every
+/// scan that reads it.
+#[salsa::tracked(returns(copy))]
+fn project_uses_django(db: &dyn Db, project: Project) -> bool {
+    project
+        .files(db)
+        .iter()
+        .any(|file| file_names_django(db, *file))
+}
+
+#[salsa::tracked(returns(copy))]
+fn file_names_django(db: &dyn Db, file: File) -> bool {
+    mentions(db, file, &[DJANGO_PACKAGE])
+}
+
+/// the role django gives `class`, from the bases it is written against
+///
+/// the walk goes up the bases rather than over the name the source writes, so a
+/// class three subclasses removed from django's own — or one that imported it
+/// under another name — is classified exactly as a direct subclass is. a base
+/// that cannot be resolved to a class contributes nothing, which leaves the
+/// class unclassified rather than guessed at.
+fn django_class_kind(
+    db: &dyn Db,
+    file: File,
+    class: &ast::StmtClassDef,
+    depth: usize,
+) -> Option<DjangoClassKind> {
+    if depth == 0 {
+        return None;
+    }
+
+    class.bases().iter().find_map(|base| {
+        resolved_class(db, file, base, |defining, resolved| {
+            if is_djangos_own(db, defining) {
+                match resolved.name.as_str() {
+                    MODEL_BASE => return Some(DjangoClassKind::Model),
+                    MODEL_ADMIN_BASE => return Some(DjangoClassKind::Admin),
+                    _ => {}
+                }
+            }
+
+            django_class_kind(db, defining, resolved, depth - 1)
+        })
+        .flatten()
+    })
+}
+
+/// whether `class` is one django's test runner would collect
+///
+/// the walk goes up the bases towards `unittest.TestCase` rather than towards
+/// any of django's own bases, because that is the one class every test case
+/// reaches: django's `SimpleTestCase` is written against it, `TestCase` is
+/// written against that, and a project's own base is written against those. a
+/// plain `unittest.TestCase` in a django project is collected by the runner just
+/// the same, so reaching it is the whole of the question.
+pub(crate) fn is_test_class(db: &dyn Db, file: File, class: &ast::StmtClassDef) -> bool {
+    fn walk(db: &dyn Db, file: File, class: &ast::StmtClassDef, depth: usize) -> bool {
+        if depth == 0 {
+            return false;
+        }
+
+        class.bases().iter().any(|base| {
+            resolved_class(db, file, base, |defining, resolved| {
+                (resolved.name.as_str() == TEST_CASE_BASE && is_unittests_own(db, defining))
+                    || walk(db, defining, resolved, depth - 1)
+            })
+            .unwrap_or_default()
+        })
+    }
+
+    walk(db, file, class, MAX_BASE_DEPTH)
+}
+
+/// whether `file` is one of `unittest`'s own modules
+fn is_unittests_own(db: &dyn Db, file: File) -> bool {
+    file_to_module(db, file)
+        .is_some_and(|module| module.name(db).components().next() == Some(UNITTEST_PACKAGE))
+}
+
+/// where the class `expr` names is declared
+fn class_ref(db: &dyn Db, file: File, expr: &Expr) -> Option<ClassRef> {
+    resolved_class(db, file, expr, |defining, class| ClassRef {
+        file: defining,
+        range: class.name.range(),
+    })
+}
+
+/// whether `file` is one of django's own modules
+fn is_djangos_own(db: &dyn Db, file: File) -> bool {
+    file_to_module(db, file).is_some_and(|module| is_djangos(db, module))
+}
+
+/// what the admin registrations of one scope say
+#[derive(Debug, Clone, PartialEq, Eq, get_size2::GetSize)]
+pub(crate) struct AdminRegistrations {
+    /// the admin classes registered
+    pub(crate) registered: Box<[ClassRef]>,
+    /// whether every registration was read in full
+    ///
+    /// a registration whose model or whose admin class could not be worked out
+    /// leaves a class registered that nothing here will ever match, which is
+    /// exactly the state in which a "nothing registers this" would be wrong.
+    pub(crate) complete: bool,
+}
+
+impl Default for AdminRegistrations {
+    fn default() -> Self {
+        Self {
+            registered: Box::default(),
+            // a module that registers nothing is one there was nothing to miss in
+            complete: true,
+        }
+    }
+}
+
+/// every admin class the project registers
+///
+/// nothing reads this yet. it is the other half of an "admin class nobody
+/// registers" diagnostic, which is written and not shipped: a check that fires
+/// in the editor and never in `by check` teaches people to distrust both, and
+/// making it reportable there means reaching the project's files from below
+/// `ty_project`. see `scratch.django.md` for the whole of it.
+#[salsa::tracked(returns(ref), heap_size=ruff_memory_usage::heap_size)]
+pub(crate) fn admin_registrations(db: &dyn Db, project: Project) -> AdminRegistrations {
+    let mut registered = Vec::new();
+    let mut complete = true;
+
+    for file in &project.files(db) {
+        // a stub declares types, never a registration django runs
+        if is_stub(db, file) {
+            continue;
+        }
+
+        let found = admin_registrations_in_file(db, file);
+        registered.extend(found.registered.iter().copied());
+        complete &= found.complete;
+    }
+
+    AdminRegistrations {
+        registered: registered.into_boxed_slice(),
+        complete,
+    }
+}
+
+/// the admin classes one module registers
+#[salsa::tracked(returns(ref), heap_size=ruff_memory_usage::heap_size)]
+fn admin_registrations_in_file(db: &dyn Db, file: File) -> AdminRegistrations {
+    // both forms — `admin.site.register(…)` and `@admin.register(…)` — spell the
+    // method itself, and a module that imports it under another name still
+    // writes the real one beside the alias
+    if !mentions(db, file, &[ADMIN_REGISTER_METHOD]) {
+        return AdminRegistrations::default();
+    }
+
+    let parsed = parsed_module(db, file).load(db);
+    let mut visitor = AdminRegistrationVisitor {
+        db,
+        file,
+        decorators: FxHashSet::default(),
+        registered: Vec::new(),
+        complete: true,
+    };
+    visitor.visit_body(parsed.suite());
+
+    AdminRegistrations {
+        registered: visitor.registered.into_boxed_slice(),
+        complete: visitor.complete,
+    }
+}
+
+/// what an argument of a `register(…)` call names
+enum Class {
+    /// a django model
+    Model,
+    /// a django admin class
+    Admin(ClassRef),
+    /// a class django gives no role to, or a value that is plainly no class
+    Other,
+    /// nothing this could work out
+    Unreadable,
+}
+
+struct AdminRegistrationVisitor<'db> {
+    db: &'db dyn Db,
+    file: File,
+    /// the `register(…)` calls already read as decorators
+    ///
+    /// a decorator is an expression like any other, so without this the walk
+    /// would read `@admin.register(Book)` a second time as a call registering
+    /// django's own default admin for `Book`.
+    decorators: FxHashSet<TextRange>,
+    registered: Vec<ClassRef>,
+    complete: bool,
+}
+
+impl AdminRegistrationVisitor<'_> {
+    /// the registration a `@admin.register(…)` on `class` makes
+    ///
+    /// this form names the models in the decorator and the admin class by
+    /// decorating it, so which class is registered is beyond doubt however the
+    /// models are written.
+    fn decorated(&mut self, class: &ast::StmtClassDef) {
+        for decorator in &class.decorator_list {
+            let Expr::Call(call) = &decorator.expression else {
+                continue;
+            };
+            if callee_name(&call.func).as_deref() != Some(ADMIN_REGISTER_METHOD) {
+                continue;
+            }
+            // a registration is never written as a decorator in the other form,
+            // so whatever this is, the call walk has nothing to add to it
+            self.decorators.insert(call.range());
+
+            if django_class_kind(self.db, self.file, class, MAX_BASE_DEPTH)
+                != Some(DjangoClassKind::Admin)
+            {
+                continue;
+            }
+
+            if call.arguments.args.iter().all(|model| self.is_model(model)) {
+                self.registered.push(ClassRef {
+                    file: self.file,
+                    range: class.name.range(),
+                });
+            } else {
+                self.complete = false;
+            }
+        }
+    }
+
+    /// the registration a `site.register(…)` call makes
+    ///
+    /// what identifies one is the shape of its arguments rather than the site it
+    /// is made on: a project registers as readily against an `AdminSite` of its
+    /// own as against django's, and nothing about the receiver says which.
+    ///
+    /// so a call is one of these unless it can be told apart from one. an
+    /// argument that resolves to a class django gives no role to is what tells
+    /// it apart — a rest framework router's viewset, a `singledispatch`'s type —
+    /// as is a route prefix written where django takes a model. short of that
+    /// the call counts, and a call that counts and cannot be read costs the
+    /// whole check.
+    fn register_call(&mut self, call: &ast::ExprCall) {
+        if self.decorators.contains(&call.range())
+            || callee_name(&call.func).as_deref() != Some(ADMIN_REGISTER_METHOD)
+        {
+            return;
+        }
+
+        // django's signature is `register(model_or_iterable, admin_class=None)`:
+        // without the second argument the model is given django's own default
+        // admin, and no class of the project's is named at all
+        let (Some(model), Some(admin)) = (
+            call.arguments.args.first(),
+            call.arguments.find_argument_value(ADMIN_CLASS_KEYWORD, 1),
+        ) else {
+            return;
+        };
+
+        let (model_class, admin_class) = (self.resolved(model), self.resolved(admin));
+
+        let is_someone_elses = matches!(model_class, Class::Other)
+            || matches!(admin_class, Class::Other | Class::Model);
+        if is_someone_elses {
+            return;
+        }
+
+        // an argument that cannot be read leaves an admin class registered that
+        // nothing here can match, so the answer is that there is no answer
+        let names_a_model = matches!(model_class, Class::Model) || self.is_model(model);
+        let Class::Admin(registered) = admin_class else {
+            self.complete = false;
+            return;
+        };
+        if !names_a_model {
+            self.complete = false;
+            return;
+        }
+
+        self.registered.push(registered);
+    }
+
+    /// whether `expr` names a django model, or a list of them
+    fn is_model(&self, expr: &Expr) -> bool {
+        match expr {
+            Expr::List(list) => list.elts.iter().all(|element| self.is_model(element)),
+            Expr::Tuple(tuple) => tuple.elts.iter().all(|element| self.is_model(element)),
+            _ => matches!(self.resolved(expr), Class::Model),
+        }
+    }
+
+    /// what the class `expr` names is, where it names one at all
+    fn resolved(&self, expr: &Expr) -> Class {
+        // django takes a model where a router takes its route prefix, and a
+        // string is not something this failed to read
+        if matches!(expr, Expr::StringLiteral(_)) {
+            return Class::Other;
+        }
+
+        resolved_class(self.db, self.file, expr, |defining, class| {
+            let reference = ClassRef {
+                file: defining,
+                range: class.name.range(),
+            };
+
+            match django_class_kind(self.db, defining, class, MAX_BASE_DEPTH) {
+                Some(DjangoClassKind::Model) => Class::Model,
+                Some(DjangoClassKind::Admin) => Class::Admin(reference),
+                None => Class::Other,
+            }
+        })
+        .unwrap_or(Class::Unreadable)
+    }
+}
+
+impl<'ast> Visitor<'ast> for AdminRegistrationVisitor<'_> {
+    fn visit_stmt(&mut self, stmt: &'ast Stmt) {
+        if let Stmt::ClassDef(class) = stmt {
+            self.decorated(class);
+        }
+
+        walk_stmt(self, stmt);
+    }
+
+    fn visit_expr(&mut self, expr: &'ast Expr) {
+        if let Expr::Call(call) = expr {
+            self.register_call(call);
+        }
+
+        walk_expr(self, expr);
+    }
+}
+
 /// the value and name range of a class-body assignment to `attribute`
 pub(crate) fn class_attribute<'ast>(
     statement: &'ast Stmt,
@@ -3193,11 +4053,12 @@ fn docstring_summary(body: &[Stmt]) -> Option<Box<str>> {
 mod tests {
     use ty_project::Db;
 
-    use crate::django_template::tests::TemplateTest;
+    use crate::django_template::tests::{DJANGO_BUILTINS, TemplateTest};
 
     use super::{
-        RegistrationKind, context_for_template, context_processor_variables, registrations,
-        static_files, tag_libraries, template_files, url_names,
+        RegistrationKind, context_for_template, context_processor_variables,
+        django_is_authoritative, registrations, static_files, tag_libraries, template_files,
+        url_names,
     };
 
     /// a project of python sources, with a throwaway template to anchor the
@@ -5012,4 +5873,105 @@ mod tests {
         );
         assert!(registered(&test).contains(&"i18n|localize (django)".to_string()));
     }
+
+    #[test]
+    fn a_function_registered_under_two_names_answers_to_both() {
+        // django's own `{% translate %}` and `{% trans %}` are one function
+        // carrying two `@register.tag` decorators, and both spellings work
+        let test = installed(
+            "
+            INSTALLED_APPS = []
+            ",
+            &[],
+            &[
+                ("django/__init__.py", ""),
+                ("django/templatetags/__init__.py", ""),
+                (
+                    "django/templatetags/i18n.py",
+                    "
+                    from django.template import Library
+
+                    register = Library()
+
+                    @register.tag('translate')
+                    @register.tag('trans')
+                    def do_translate(parser, token): ...
+                    ",
+                ),
+            ],
+        );
+
+        assert_eq!(
+            registered(&test),
+            ["i18n|translate (django)", "i18n|trans (django)"]
+        );
+    }
+
+    #[test]
+    fn djangos_implicit_builtins_are_discovered_as_libraries_nothing_has_to_load() {
+        let test = installed(
+            "
+            INSTALLED_APPS = []
+            ",
+            &[],
+            DJANGO_BUILTINS,
+        );
+
+        assert_eq!(
+            libraries(&test),
+            [
+                "defaulttags (Django, always loaded)",
+                "defaultfilters (Django, always loaded)",
+                "loader_tags (Django, always loaded)",
+            ],
+            "`Engine.default_builtins` are libraries like any other, bar the loading"
+        );
+        assert_eq!(
+            registered(&test),
+            [
+                "defaulttags|for (django)",
+                "defaulttags|if (django)",
+                "defaulttags|squish (django)",
+                "defaultfilters|upper (django)",
+                "defaultfilters|shorten (django)",
+                "loader_tags|block (django)",
+                "loader_tags|extends (django)",
+                "loader_tags|include (django)",
+            ]
+        );
+    }
+
+    #[test]
+    fn a_django_whose_builtins_were_read_is_authoritative() {
+        let test = installed(
+            "
+            INSTALLED_APPS = []
+            ",
+            &[],
+            DJANGO_BUILTINS,
+        );
+
+        assert!(django_is_authoritative(&test.db, test.db.project()));
+    }
+
+    #[test]
+    fn a_django_that_cannot_be_read_is_never_authoritative() {
+        // this mock has a `templatetags` package but no `django.template`, so
+        // none of what django itself registers was read
+        let test = installed(
+            "
+            INSTALLED_APPS = ['django.contrib.humanize']
+            ",
+            &[],
+            DJANGO,
+        );
+        assert!(!django_is_authoritative(&test.db, test.db.project()));
+
+        // and a project with no settings module reaches nothing installed at all
+        let test = TemplateTest::with_site_packages(
+            &[("app/templates/app/page.html", "<CURSOR>")],
+            DJANGO_BUILTINS,
+        );
+        assert!(!django_is_authoritative(&test.db, test.db.project()));
+    }
 }
diff --git a/crates/ty_ide/src/django_template/python.rs b/crates/ty_ide/src/django_template/python.rs
index 473b1fcab7..5be536dd6a 100644
--- a/crates/ty_ide/src/django_template/python.rs
+++ b/crates/ty_ide/src/django_template/python.rs
@@ -21,8 +21,8 @@ use crate::completion::CompletionKind;
 use crate::{NavigationTarget, NavigationTargets, RangedValue};
 
 use super::project::{
-    self, CONTEXT_CALLEES, REDIRECT_CALLEE, REVERSE_CALLEES, TEMPLATE_NAME_ATTRIBUTE, callee_name,
-    class_attribute,
+    self, CONTEXT_CALLEES, REDIRECT_CALLEE, REVERSE_ARGUMENTS_KEYWORD, REVERSE_CALLEES,
+    REVERSE_NAME_KEYWORD, TEMPLATE_NAME_ATTRIBUTE, callee_name, class_attribute,
 };
 
 /// what a string literal in a python module names
@@ -53,7 +53,13 @@ pub(crate) fn string_completions<'a>(
     db: &dyn Db,
     ancestors: impl Iterator<Item = AnyNodeRef<'a>>,
 ) -> Vec<StringCompletion> {
-    let Some((string, names)) = named(ancestors) else {
+    let ancestors: Vec<AnyNodeRef<'a>> = ancestors.collect();
+
+    if let Some(completions) = route_arguments(db, &ancestors) {
+        return completions;
+    }
+
+    let Some((string, names)) = named(ancestors.iter().copied()) else {
         return Vec::new();
     };
     let Some(range) = contents(string) else {
@@ -183,6 +189,82 @@ fn named<'a>(
     Some((string, names))
 }
 
+/// the arguments the route a `reverse()` names still takes, where the literal
+/// among `ancestors` is one of their names
+///
+/// `reverse("blog:detail", kwargs={"pk": 1})` names the route's arguments in the
+/// keys of that dict, exactly as a `{% url 'blog:detail' pk=1 %}` names them —
+/// and a key the user is still typing is a set as far as the parser is
+/// concerned, so both spellings are read.
+///
+/// `None` where the position is not one of those keys, which is the difference
+/// between a route that takes nothing more and a literal that names no argument
+/// at all.
+fn route_arguments(db: &dyn Db, ancestors: &[AnyNodeRef<'_>]) -> Option<Vec<StringCompletion>> {
+    let (index, string) = ancestors
+        .iter()
+        .enumerate()
+        .find_map(|(index, node)| match node {
+            AnyNodeRef::ExprStringLiteral(string) => Some((index, *string)),
+            _ => None,
+        })?;
+    let range = contents(string)?;
+
+    let mut enclosing = ancestors[index + 1..].iter();
+    let keys: Vec<&ast::Expr> = match enclosing.next()? {
+        // a literal in a value position names an argument's value, not its name
+        AnyNodeRef::ExprDict(dict) => dict
+            .items
+            .iter()
+            .filter_map(|item| item.key.as_ref())
+            .collect(),
+        AnyNodeRef::ExprSet(set) => set.elts.iter().collect(),
+        _ => return None,
+    };
+    if !keys.iter().any(|key| key.range() == string.range()) {
+        return None;
+    }
+
+    let AnyNodeRef::Keyword(keyword) = enclosing.next()? else {
+        return None;
+    };
+    if keyword.arg.as_ref().map(ast::Identifier::as_str) != Some(REVERSE_ARGUMENTS_KEYWORD) {
+        return None;
+    }
+
+    let AnyNodeRef::ExprCall(call) =
+        enclosing.find(|node| !matches!(node, AnyNodeRef::Arguments(_)))?
+    else {
+        return None;
+    };
+    if !REVERSE_CALLEES.contains(&callee_name(&call.func)?.as_str()) {
+        return None;
+    }
+
+    let route = call
+        .arguments
+        .find_argument_value(REVERSE_NAME_KEYWORD, 0)?
+        .as_string_literal_expr()?;
+
+    let given: FxHashSet<&str> = keys
+        .iter()
+        .filter(|key| key.range() != string.range())
+        .filter_map(|key| Some(key.as_string_literal_expr()?.value.to_str()))
+        .collect();
+
+    Some(
+        project::route_parameters(db, route.value.to_str())
+            .into_iter()
+            .filter(|parameter| !given.contains(parameter.name.as_str()))
+            .map(|parameter| StringCompletion {
+                name: parameter.name,
+                kind: CompletionKind::Field,
+                range,
+            })
+            .collect(),
+    )
+}
+
 /// what the argument `string` of `call` names
 fn argument(call: &ast::ExprCall, string: &ast::ExprStringLiteral) -> Option<Names> {
     let callee = callee_name(&call.func)?;
diff --git a/crates/ty_ide/src/django_template/signature_help.rs b/crates/ty_ide/src/django_template/signature_help.rs
new file mode 100644
index 0000000000..cffbbe161e
--- /dev/null
+++ b/crates/ty_ide/src/django_template/signature_help.rs
@@ -0,0 +1,465 @@
+//! signature help for django templates
+//!
+//! a filter argument is the one thing a template writes that nothing on the page
+//! explains. `{{ value|date:"Y-m-d" }}` says which filter runs, and every other
+//! service in this module can say what `value` is, but what may follow the colon
+//! is written nowhere the reader can see.
+//!
+//! django calls a filter with the value it was applied to and, where the template
+//! wrote one, the argument — so the argument *is* the registered function's second
+//! parameter. wherever that function can be read, which is the project's own
+//! filters and django's own too whenever django itself is readable, the answer is
+//! a real python parameter. where it cannot be read, django's description of the
+//! filter is still more than the template says on its own.
+
+use ruff_db::parsed::parsed_module;
+use ruff_python_ast::find_node::covering_node;
+use ruff_python_ast::{self as ast, AnyNodeRef, Expr};
+use ruff_text_size::TextSize;
+use ty_project::Db;
+use ty_python_semantic::SemanticModel;
+use ty_python_semantic::types::ide_support::hintable_parameter_type;
+
+use super::builtins;
+use super::index::TemplateIndex;
+use super::lexer::{ConstructKind, Token, TokenKind};
+use super::project::{self, Registration, RegistrationKind};
+
+/// what django names the flag it fills in itself, on the decorator and on the
+/// parameter it fills
+const AUTOESCAPE_FLAG: &str = "needs_autoescape";
+const AUTOESCAPE: &str = "autoescape";
+
+/// what the filter argument under the cursor takes
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct TemplateSignature {
+    /// the filter and its argument, written the way the template writes them
+    pub label: String,
+    /// the argument's own text within [`Self::label`], where the filter's
+    /// function could be read and does take one
+    pub parameter: Option<String>,
+    /// what the filter is documented to do
+    pub documentation: Option<String>,
+}
+
+/// what the filter whose argument `offset` sits in takes
+pub(crate) fn signature_help(
+    db: &dyn Db,
+    index: &TemplateIndex,
+    source: &str,
+    offset: TextSize,
+) -> Option<TemplateSignature> {
+    let construct = index.lexed().construct_at(offset)?;
+    if construct.kind == ConstructKind::Comment {
+        return None;
+    }
+
+    let name = filter_argument_at(source, index.lexed().construct_tokens(construct), offset)?;
+
+    signature(db, name)
+}
+
+/// the filter whose argument `offset` sits in
+///
+/// an argument runs from the `:` after the filter's name to whatever ends it: the
+/// `|` starting the next filter, or the construct's closing delimiter. the cursor
+/// counts as inside it anywhere in there, the empty position directly after the
+/// colon included — which is where it sits the moment the colon is typed.
+fn filter_argument_at<'src>(
+    source: &'src str,
+    tokens: &[Token],
+    offset: TextSize,
+) -> Option<&'src str> {
+    for (index, token) in tokens.iter().enumerate() {
+        if token.kind != TokenKind::FilterName {
+            continue;
+        }
+
+        let Some(colon) = tokens
+            .get(index + 1)
+            .filter(|token| is_operator(source, token, ":"))
+        else {
+            continue;
+        };
+
+        let end = tokens
+            .get(index + 2..)
+            .unwrap_or_default()
+            .iter()
+            .take_while(|token| {
+                token.kind != TokenKind::Delimiter && !is_operator(source, token, "|")
+            })
+            .last()
+            .map_or(colon.range.end(), |token| token.range.end());
+
+        if (colon.range.end()..=end).contains(&offset) {
+            return Some(&source[token.range]);
+        }
+    }
+
+    None
+}
+
+fn is_operator(source: &str, token: &Token, operator: &str) -> bool {
+    token.kind == TokenKind::Operator && &source[token.range] == operator
+}
+
+/// what the filter `name` takes
+fn signature(db: &dyn Db, name: &str) -> Option<TemplateSignature> {
+    let registered = filter_registration(db, name);
+
+    // as for hover: the table documents django's own filters, but which of them
+    // this django has is that django's to say. a project's filter is documented
+    // by its docstring and by nothing else
+    let documentation = builtins::filter(name)
+        .filter(|_| builtins::provided_by_django(db, name, true).is_some())
+        .map(|filter| filter.documentation.to_string())
+        .or_else(|| {
+            registered
+                .and_then(|registration| registration.documentation.as_deref())
+                .map(str::to_string)
+        });
+
+    let Some(registration) = registered else {
+        // a django this project cannot read still has a documented filter set,
+        // and saying what the filter does is more than the template says
+        return Some(TemplateSignature {
+            label: format!("|{name}"),
+            parameter: None,
+            documentation: Some(documentation?),
+        });
+    };
+
+    // a function taking only the value takes no argument, and a filter that takes
+    // no argument has nothing to say about the one that was written
+    let parameter = argument_parameter(db, registration)?;
+
+    Some(TemplateSignature {
+        label: format!("|{name}:{parameter}"),
+        parameter: Some(parameter),
+        documentation,
+    })
+}
+
+/// the registration of the filter `name`, django's own or the project's
+fn filter_registration<'db>(db: &'db dyn Db, name: &str) -> Option<&'db Registration> {
+    project::registrations(db, db.project())
+        .iter()
+        .find(|registration| {
+            registration.kind == RegistrationKind::Filter && registration.name == name
+        })
+}
+
+/// the registered function's argument parameter, as the signature writes it
+///
+/// this is its *second* parameter: django passes the value being filtered first.
+/// the type is written down only where the parameter is *annotated*. django's own
+/// filters annotate almost none of theirs, and what an unannotated parameter
+/// infers to says nothing the reader wants: `def date(value, arg=None)` would put
+/// `arg: Unknown | None` in front of somebody looking for a format string.
+fn argument_parameter(db: &dyn Db, registration: &Registration) -> Option<String> {
+    let parsed = parsed_module(db, registration.file).load(db);
+    let covering = covering_node(parsed.syntax().into(), registration.range)
+        .find_first(|node| node.is_stmt_function_def())
+        .ok()?;
+    let AnyNodeRef::StmtFunctionDef(function) = covering.node() else {
+        return None;
+    };
+
+    let injected = needs_autoescape(function).then_some(AUTOESCAPE);
+    let parameter = &function
+        .parameters
+        .posonlyargs
+        .iter()
+        .chain(&function.parameters.args)
+        .filter(|parameter| Some(parameter.parameter.name.as_str()) != injected)
+        .nth(1)?
+        .parameter;
+    let name = parameter.name.as_str();
+
+    let annotated = parameter.annotation.is_some();
+    let model = SemanticModel::new(db, registration.file);
+
+    match hintable_parameter_type(&model, parameter).filter(|_| annotated) {
+        Some(ty) => Some(format!("{name}: {}", ty.display(db))),
+        None => Some(name.to_string()),
+    }
+}
+
+/// whether django fills a parameter of this filter in itself
+///
+/// `@register.filter(needs_autoescape=True)` makes django call the function with
+/// an extra `autoescape=` keyword of its own, so the parameter taking it is
+/// django's rather than the argument the template writes. django's own
+/// `{{ x|urlize }}` is a filter that takes no argument and has two parameters
+/// because of it.
+fn needs_autoescape(function: &ast::StmtFunctionDef) -> bool {
+    function.decorator_list.iter().any(|decorator| {
+        let Expr::Call(call) = &decorator.expression else {
+            return false;
+        };
+
+        call.arguments.find_keyword(AUTOESCAPE_FLAG).is_some_and(
+            |keyword| matches!(&keyword.value, Expr::BooleanLiteral(literal) if literal.value),
+        )
+    })
+}
+
+#[cfg(test)]
+mod tests {
+    use crate::django_template::tests::{DJANGO_BUILTINS, TemplateTest};
+
+    /// the same small django project the hover and completion tests use, with a
+    /// filter of the project's own that takes an argument and one that does not
+    fn project(template: &str) -> TemplateTest {
+        TemplateTest::new(&[
+            (
+                "blog/models.py",
+                "
+                class Book:
+                    title: str
+                ",
+            ),
+            (
+                "blog/views.py",
+                "
+                from blog.models import Book
+
+                def post(request):
+                    return render(request, 'blog/post.html', {'book': Book()})
+                ",
+            ),
+            (
+                "blog/templatetags/blog_extras.py",
+                "
+                from django import template
+
+                register = template.Library()
+
+                @register.filter
+                def shout(value, suffix: str):
+                    'shouts it.'
+                    return value
+
+                @register.filter
+                def quieten(value):
+                    'quietens it.'
+                    return value
+                ",
+            ),
+            ("blog/templates/blog/post.html", template),
+        ])
+    }
+
+    #[test]
+    fn a_project_filters_argument_is_its_functions_second_parameter() {
+        assert_eq!(
+            project(r#"{{ book.title|shout:"<CURSOR>" }}"#).signature(),
+            "|shout:suffix: str [suffix: str] — shouts it."
+        );
+    }
+
+    #[test]
+    fn an_unannotated_argument_is_offered_by_name_alone() {
+        let test = TemplateTest::new(&[
+            (
+                "blog/templatetags/blog_extras.py",
+                "
+                from django import template
+
+                register = template.Library()
+
+                @register.filter
+                def shout(value, suffix):
+                    'shouts it.'
+                    return value
+                ",
+            ),
+            (
+                "blog/templates/blog/post.html",
+                r#"{{ title|shout:"<CURSOR>" }}"#,
+            ),
+        ]);
+
+        assert_eq!(test.signature(), "|shout:suffix [suffix] — shouts it.");
+    }
+
+    #[test]
+    fn an_unannotated_argument_with_a_default_is_not_typed_from_it() {
+        // this is how django writes almost all of its own: `arg: Unknown | None`
+        // says nothing to somebody looking for what may follow the colon
+        let test = TemplateTest::new(&[
+            (
+                "blog/templatetags/blog_extras.py",
+                "
+                from django import template
+
+                register = template.Library()
+
+                @register.filter
+                def shout(value, suffix=None):
+                    'shouts it.'
+                    return value
+                ",
+            ),
+            (
+                "blog/templates/blog/post.html",
+                r#"{{ title|shout:"<CURSOR>" }}"#,
+            ),
+        ]);
+
+        assert_eq!(test.signature(), "|shout:suffix [suffix] — shouts it.");
+    }
+
+    #[test]
+    fn the_parameter_django_fills_itself_is_not_the_templates_argument() {
+        // `{{ x|urlize }}` is exactly this: two parameters, no argument
+        let test = TemplateTest::new(&[
+            (
+                "blog/templatetags/blog_extras.py",
+                "
+                from django import template
+
+                register = template.Library()
+
+                @register.filter(is_safe=True, needs_autoescape=True)
+                def shout(value, autoescape=True):
+                    'shouts it.'
+                    return value
+                ",
+            ),
+            (
+                "blog/templates/blog/post.html",
+                r#"{{ title|shout:"<CURSOR>" }}"#,
+            ),
+        ]);
+
+        assert_eq!(test.signature(), "no signature");
+    }
+
+    #[test]
+    fn a_filter_django_fills_a_parameter_of_can_still_take_an_argument() {
+        let test = TemplateTest::new(&[
+            (
+                "blog/templatetags/blog_extras.py",
+                "
+                from django import template
+
+                register = template.Library()
+
+                @register.filter(needs_autoescape=True)
+                def pad(value, width: int, autoescape=True):
+                    'pads it.'
+                    return value
+                ",
+            ),
+            (
+                "blog/templates/blog/post.html",
+                r#"{{ title|pad:"<CURSOR>" }}"#,
+            ),
+        ]);
+
+        assert_eq!(test.signature(), "|pad:width: int [width: int] — pads it.");
+    }
+
+    #[test]
+    fn a_filter_that_takes_no_argument_offers_nothing() {
+        assert_eq!(
+            project(r#"{{ book.title|quieten:"<CURSOR>" }}"#).signature(),
+            "no signature"
+        );
+    }
+
+    #[test]
+    fn a_cursor_that_is_not_in_an_argument_offers_nothing() {
+        assert_eq!(
+            project("{{ book.ti<CURSOR>tle|shout:'!' }}").signature(),
+            "no signature"
+        );
+        assert_eq!(
+            project("{{ book.title|sho<CURSOR>ut:'!' }}").signature(),
+            "no signature"
+        );
+        assert_eq!(
+            project("{{ book.ti<CURSOR>tle }}").signature(),
+            "no signature"
+        );
+    }
+
+    #[test]
+    fn a_cursor_directly_after_the_colon_is_in_the_argument() {
+        assert_eq!(
+            project("{{ book.title|shout:<CURSOR> }}").signature(),
+            "|shout:suffix: str [suffix: str] — shouts it."
+        );
+    }
+
+    #[test]
+    fn only_the_filter_the_cursor_is_in_answers() {
+        assert_eq!(
+            project(r#"{{ book.title|quieten|shout:"<CURSOR>" }}"#).signature(),
+            "|shout:suffix: str [suffix: str] — shouts it."
+        );
+    }
+
+    #[test]
+    fn a_django_filter_reads_its_argument_from_the_installed_django() {
+        let test = TemplateTest::with_site_packages(
+            &[
+                (
+                    "manage.py",
+                    "
+                    import os
+
+                    os.environ.setdefault('DJANGO_SETTINGS_MODULE', 'project.settings')
+                    ",
+                ),
+                ("project/__init__.py", ""),
+                (
+                    "project/settings.py",
+                    "
+                    INSTALLED_APPS = []
+
+                    TEMPLATES = [{'DIRS': [], 'APP_DIRS': True, 'OPTIONS': {}}]
+                    ",
+                ),
+                (
+                    "app/templates/app/page.html",
+                    r#"{{ value|shorten:"<CURSOR>" }}"#,
+                ),
+            ],
+            DJANGO_BUILTINS,
+        );
+
+        assert_eq!(test.signature(), "|shorten:arg [arg]");
+    }
+
+    #[test]
+    fn a_django_filter_with_no_readable_django_is_offered_by_its_documentation() {
+        let test = TemplateTest::new(&[(
+            "blog/templates/blog/post.html",
+            r#"{{ value|date:"<CURSOR>" }}"#,
+        )]);
+
+        assert_eq!(
+            test.signature(),
+            "|date — formats a date with the given format string."
+        );
+    }
+
+    #[test]
+    fn a_filter_nothing_knows_offers_nothing() {
+        assert_eq!(
+            project(r#"{{ book.title|mystery:"<CURSOR>" }}"#).signature(),
+            "no signature"
+        );
+    }
+
+    #[test]
+    fn a_comment_offers_nothing() {
+        assert_eq!(
+            project(r#"{# book.title|shout:"<CURSOR>" #}"#).signature(),
+            "no signature"
+        );
+    }
+}
diff --git a/crates/ty_ide/src/django_template/symbols.rs b/crates/ty_ide/src/django_template/symbols.rs
index 51669d7989..df8941200b 100644
--- a/crates/ty_ide/src/django_template/symbols.rs
+++ b/crates/ty_ide/src/django_template/symbols.rs
@@ -1,15 +1,28 @@
-//! the outline of a django template
+//! the outline of a django template, and the project's django names
 //!
 //! what a template declares is its `{% block %}`s and its `{% partialdef %}`s:
 //! the names a child template can override and the fragments a `{% partial %}`
 //! can render. everything else in the file is markup, which the editor outlines
 //! far better than this could.
+//!
+//! [`workspace_symbols`] is the project-wide half of the same idea: the models,
+//! admin classes, views, routes, templates, tags and filters a django project is
+//! made of, so that a search across the workspace finds them by the names django
+//! knows them by.
+
+use std::borrow::Cow;
 
+use ruff_db::files::{File, system_path_to_file};
 use ruff_text_size::TextRange;
+use rustc_hash::FxHashSet;
+use ty_project::Db;
 
+use crate::symbols::QueryPattern;
 use crate::{SymbolInfo, SymbolKind};
 
 use super::index::{Definition, TemplateIndex};
+use super::project::{self, DjangoClassKind, RegistrationKind, TargetKind};
+use super::template_index;
 
 /// one entry of a template's outline
 #[derive(Debug, Clone, PartialEq, Eq)]
@@ -85,6 +98,170 @@ pub(crate) fn document_symbols(index: &TemplateIndex) -> Vec<TemplateSymbol> {
     roots
 }
 
+/// one django thing a workspace symbol search can find
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct DjangoSymbol {
+    pub symbol: SymbolInfo<'static>,
+    pub file: File,
+    /// what django calls this kind of thing
+    ///
+    /// a model and an admin class are both classes python has already offered
+    /// under the same name, and this is the whole of what tells them apart in a
+    /// list of results.
+    pub container: &'static str,
+}
+
+impl DjangoSymbol {
+    fn new(
+        name: impl Into<String>,
+        kind: SymbolKind,
+        container: &'static str,
+        file: File,
+        name_range: TextRange,
+        full_range: TextRange,
+    ) -> Self {
+        Self {
+            symbol: SymbolInfo {
+                name: Cow::Owned(name.into()),
+                kind,
+                deprecated: false,
+                imported_from: None,
+                name_range,
+                full_range,
+            },
+            file,
+            container,
+        }
+    }
+}
+
+/// every django thing of the project whose name matches `query`
+///
+/// these are *added* to what python contributes rather than folded into it. some
+/// of them — a route name, a template's loader name, a `{% partialdef %}` — are
+/// names python never had at all. the rest are things python has already offered
+/// as a plain class or function, and what this adds is which of them django
+/// gives a role to.
+///
+/// a template's `{% block %}`s are deliberately not here. a block name is chosen
+/// against the one template it overrides rather than to be unique in a project,
+/// so a search for `content` would answer with one entry per template that
+/// declares one — hundreds of identical answers for a name that identifies
+/// nothing. a `{% partialdef %}` is the opposite: it exists to be rendered from
+/// elsewhere by name, so it is a name worth finding.
+pub(crate) fn workspace_symbols(db: &dyn Db, query: &QueryPattern) -> Vec<DjangoSymbol> {
+    let project = db.project();
+    let mut found = Vec::new();
+
+    for class in project::django_classes(db, project) {
+        if !query.is_match_symbol_name(&class.name) {
+            continue;
+        }
+        let (kind, container) = match class.kind {
+            DjangoClassKind::Model => (SymbolKind::Class, "django model"),
+            DjangoClassKind::Admin => (SymbolKind::Class, "django admin"),
+        };
+        found.push(DjangoSymbol::new(
+            class.name.as_str(),
+            kind,
+            container,
+            class.file,
+            class.range,
+            class.full_range,
+        ));
+    }
+
+    // one view answers several routes, and it is one thing however many
+    let mut seen = FxHashSet::default();
+    for route in project::url_names(db, project) {
+        if query.is_match_symbol_name(&route.name) {
+            found.push(DjangoSymbol::new(
+                route.name.as_str(),
+                SymbolKind::Constant,
+                "django route",
+                route.file,
+                route.range,
+                route.range,
+            ));
+        }
+
+        if let Some(view) = &route.view
+            && query.is_match_symbol_name(&view.name)
+            && seen.insert((view.file, view.range))
+        {
+            found.push(DjangoSymbol::new(
+                view.name.as_str(),
+                match view.kind {
+                    TargetKind::Class => SymbolKind::Class,
+                    TargetKind::Function => SymbolKind::Function,
+                },
+                "django view",
+                view.file,
+                view.range,
+                view.full_range,
+            ));
+        }
+    }
+
+    for registration in project::registrations(db, project) {
+        // django's own `{% for %}` and `|upper` are the language rather than
+        // anything this project is made of
+        if registration.django || !query.is_match_symbol_name(&registration.name) {
+            continue;
+        }
+        let container = match registration.kind {
+            RegistrationKind::Tag { .. } => "django tag",
+            RegistrationKind::Filter => "django filter",
+        };
+        found.push(DjangoSymbol::new(
+            registration.name.as_str(),
+            SymbolKind::Function,
+            container,
+            registration.file,
+            registration.range,
+            registration.range,
+        ));
+    }
+
+    for template in project::template_files(db, project) {
+        // an installed app's templates are django's to render and nobody's to
+        // search for
+        if !template.own {
+            continue;
+        }
+        let Ok(file) = system_path_to_file(db, &template.path) else {
+            continue;
+        };
+
+        if query.is_match_symbol_name(&template.name) {
+            found.push(DjangoSymbol::new(
+                template.name.as_str(),
+                SymbolKind::Module,
+                "django template",
+                file,
+                TextRange::default(),
+                TextRange::default(),
+            ));
+        }
+
+        for partial in template_index(db, file).partials() {
+            if !query.is_match_symbol_name(&partial.name) {
+                continue;
+            }
+            found.push(DjangoSymbol::new(
+                partial.name.as_str(),
+                SymbolKind::Function,
+                "django partial",
+                file,
+                partial.name_range,
+                partial.full_range,
+            ));
+        }
+    }
+
+    found
+}
+
 /// hand a finished symbol to the declaration enclosing it, or to the outline
 fn attach(symbol: TemplateSymbol, open: &mut [TemplateSymbol], roots: &mut Vec<TemplateSymbol>) {
     match open.last_mut() {
@@ -95,7 +272,7 @@ fn attach(symbol: TemplateSymbol, open: &mut [TemplateSymbol], roots: &mut Vec<T
 
 #[cfg(test)]
 mod tests {
-    use crate::django_template::tests::TemplateTest;
+    use crate::django_template::tests::{DJANGO_ADMIN, TemplateTest};
 
     fn template(source: &str) -> TemplateTest {
         TemplateTest::new(&[("blog/templates/blog/post.html", source)])
@@ -144,4 +321,195 @@ mod tests {
                 .is_empty()
         );
     }
+
+    // ---- the project's django names, for a workspace search ---------------
+
+    /// a whole django project: models, an admin module, views, a url tree, a tag
+    /// library and templates, with django installed beside it
+    fn workspace() -> TemplateTest {
+        TemplateTest::with_site_packages(
+            &[
+                (
+                    "manage.py",
+                    "
+                    import os
+
+                    os.environ.setdefault('DJANGO_SETTINGS_MODULE', 'project.settings')
+                    ",
+                ),
+                ("project/__init__.py", ""),
+                (
+                    "project/settings.py",
+                    "
+                    INSTALLED_APPS = ['blog']
+
+                    TEMPLATES = [{'DIRS': [], 'APP_DIRS': True, 'OPTIONS': {}}]
+
+                    ROOT_URLCONF = 'project.urls'
+                    ",
+                ),
+                (
+                    "project/urls.py",
+                    "
+                    from django.urls import include, path
+
+                    urlpatterns = [path('blog/', include('blog.urls'))]
+                    ",
+                ),
+                ("blog/__init__.py", ""),
+                (
+                    "blog/models.py",
+                    "
+                    from django.db import models
+
+
+                    class Book(models.Model): ...
+                    ",
+                ),
+                (
+                    "blog/admin.py",
+                    "
+                    from django.contrib import admin
+
+                    from blog.models import Book
+
+
+                    @admin.register(Book)
+                    class BookAdmin(admin.ModelAdmin): ...
+                    ",
+                ),
+                (
+                    "blog/views.py",
+                    "
+                    def listing(request): ...
+
+
+                    class BookDetail: ...
+                    ",
+                ),
+                (
+                    "blog/urls.py",
+                    "
+                    from django.urls import path
+
+                    from blog import views
+
+                    app_name = 'blog'
+
+                    urlpatterns = [
+                        path('', views.listing, name='index'),
+                        path('<int:pk>/', views.BookDetail.as_view(), name='detail'),
+                    ]
+                    ",
+                ),
+                ("blog/templatetags/__init__.py", ""),
+                (
+                    "blog/templatetags/blog_extras.py",
+                    "
+                    from django import template
+
+                    register = template.Library()
+
+                    @register.filter
+                    def shout(value):
+                        return value
+
+                    @register.simple_tag
+                    def badge():
+                        return ''
+                    ",
+                ),
+                (
+                    "blog/templates/blog/post.html",
+                    "{% partialdef card %}a{% endpartialdef %}{% block content %}b{% endblock %}",
+                ),
+            ],
+            DJANGO_ADMIN,
+        )
+    }
+
+    #[test]
+    fn a_model_is_found_as_one_beside_the_class_python_offers() {
+        assert_eq!(
+            workspace().workspace_symbols("Book"),
+            [
+                "django admin BookAdmin [/src/blog/admin.py]",
+                "django model Book [/src/blog/models.py]",
+                "django view BookDetail [/src/blog/views.py]",
+                "python Book [/src/blog/models.py]",
+                "python BookAdmin [/src/blog/admin.py]",
+                "python BookDetail [/src/blog/views.py]",
+            ]
+        );
+    }
+
+    #[test]
+    fn a_route_is_found_by_the_name_the_url_tree_gives_it() {
+        assert_eq!(
+            workspace().workspace_symbols("blog:detail"),
+            ["django route blog:detail [/src/blog/urls.py]"]
+        );
+    }
+
+    #[test]
+    fn a_view_is_found_by_its_own_name() {
+        assert_eq!(
+            workspace().workspace_symbols("listing"),
+            [
+                "django view listing [/src/blog/views.py]",
+                "python listing [/src/blog/views.py]",
+            ]
+        );
+    }
+
+    #[test]
+    fn a_template_is_found_by_the_name_the_loader_uses() {
+        assert_eq!(
+            workspace().workspace_symbols("blog/post"),
+            ["django template blog/post.html [/src/blog/templates/blog/post.html]"]
+        );
+    }
+
+    #[test]
+    fn a_partial_is_found_by_its_name() {
+        assert_eq!(
+            workspace().workspace_symbols("card"),
+            ["django partial card [/src/blog/templates/blog/post.html]"]
+        );
+    }
+
+    #[test]
+    fn a_block_is_not_a_workspace_symbol() {
+        // see `workspace_symbols`: a project has one `content` per template, and
+        // a name that identifies nothing is worth nothing to a search
+        assert_eq!(
+            workspace().workspace_symbols("content"),
+            Vec::<String>::new()
+        );
+    }
+
+    #[test]
+    fn a_tag_and_a_filter_are_found_by_the_names_a_template_writes() {
+        assert_eq!(
+            workspace().workspace_symbols("badge"),
+            [
+                "django tag badge [/src/blog/templatetags/blog_extras.py]",
+                "python badge [/src/blog/templatetags/blog_extras.py]",
+            ]
+        );
+        assert_eq!(
+            workspace().workspace_symbols("shout"),
+            [
+                "django filter shout [/src/blog/templatetags/blog_extras.py]",
+                "python shout [/src/blog/templatetags/blog_extras.py]",
+            ]
+        );
+    }
+
+    #[test]
+    fn a_project_that_is_no_django_project_answers_exactly_what_python_does() {
+        let test = TemplateTest::new(&[("app.py", "class Book:\n    pass\n")]);
+
+        assert_eq!(test.workspace_symbols("Book"), ["python Book [/app.py]"]);
+    }
 }
diff --git a/crates/ty_ide/src/inlay_hints.rs b/crates/ty_ide/src/inlay_hints.rs
index ff7caeb905..5c06f4fcc3 100644
--- a/crates/ty_ide/src/inlay_hints.rs
+++ b/crates/ty_ide/src/inlay_hints.rs
@@ -675,6 +675,22 @@ pub struct InlayHintSettings {
     /// f("a=b")
     /// ```
     pub implicit_arguments: bool,
+
+    /// django templates: whether to show the element type a `{% for %}` binding
+    /// takes.
+    ///
+    /// ```django-html
+    /// {% for book": Book" in shelf %}
+    /// ```
+    pub template_binding_types: bool,
+
+    /// django templates: whether to show the file an `{% extends %}` or an
+    /// `{% include %}` name resolves to.
+    ///
+    /// ```django-html
+    /// {% include "card.html"" → blog/templates/blog/card.html" %}
+    /// ```
+    pub resolved_templates: bool,
     // Add any new setting that enables additional inlays to `any_enabled`.
 }
 
@@ -695,6 +711,8 @@ impl InlayHintSettings {
             implicit_parameters: false,
             lambda_parameter_types: false,
             implicit_arguments: false,
+            template_binding_types: false,
+            resolved_templates: false,
         }
     }
 
@@ -713,6 +731,8 @@ impl InlayHintSettings {
             implicit_parameters,
             lambda_parameter_types,
             implicit_arguments,
+            template_binding_types,
+            resolved_templates,
         } = *self;
 
         variable_types
@@ -728,6 +748,8 @@ impl InlayHintSettings {
             || implicit_parameters
             || lambda_parameter_types
             || implicit_arguments
+            || template_binding_types
+            || resolved_templates
     }
 }
 
@@ -747,6 +769,8 @@ impl Default for InlayHintSettings {
             implicit_parameters: true,
             lambda_parameter_types: true,
             implicit_arguments: true,
+            template_binding_types: true,
+            resolved_templates: true,
         }
     }
 }
diff --git a/crates/ty_ide/src/lib.rs b/crates/ty_ide/src/lib.rs
index 7d29fdc8be..c901f2171f 100644
--- a/crates/ty_ide/src/lib.rs
+++ b/crates/ty_ide/src/lib.rs
@@ -41,12 +41,14 @@ pub use completion::{
     CompletionSettings, completion,
 };
 pub use django_template::{
-    DisplayTemplateHover, PreparedTemplateRename, TemplateCompletion, TemplateEdit, TemplateHover,
-    TemplateRename, TemplateRenameOutcome, TemplateSymbol, django_prepare_rename,
-    django_references, django_rename, django_template_completions, django_template_diagnostics,
-    django_template_document_symbols, django_template_folding_ranges,
-    django_template_goto_definition, django_template_hover, django_template_semantic_tokens,
-    is_django_template_path,
+    DisplayTemplateHover, DjangoCodeLens, DjangoLensAction, DjangoLensTarget, DjangoSymbol,
+    PreparedTemplateRename, TemplateCompletion, TemplateEdit, TemplateHover, TemplateInlayHint,
+    TemplateInlayHintKind, TemplateRename, TemplateRenameOutcome, TemplateSignature,
+    TemplateSymbol, django_manage_script, django_prepare_rename, django_python_code_lenses,
+    django_references, django_rename, django_template_code_lenses, django_template_completions,
+    django_template_diagnostics, django_template_document_symbols, django_template_folding_ranges,
+    django_template_goto_definition, django_template_hover, django_template_inlay_hints,
+    django_template_semantic_tokens, django_template_signature_help, is_django_template_path,
 };
 pub use doc_highlights::document_highlights;
 pub use document_symbols::document_symbols;
diff --git a/crates/ty_ide/src/workspace_symbols.rs b/crates/ty_ide/src/workspace_symbols.rs
index 6a4e2799a4..8833188ec8 100644
--- a/crates/ty_ide/src/workspace_symbols.rs
+++ b/crates/ty_ide/src/workspace_symbols.rs
@@ -1,3 +1,4 @@
+use crate::django_template::django_workspace_symbols;
 use crate::symbols::{QueryPattern, SymbolInfo, symbols_for_file};
 use rayon::prelude::*;
 use ruff_db::files::File;
@@ -20,7 +21,7 @@ pub fn workspace_symbols(db: &dyn Db, query: &str) -> Vec<WorkspaceSymbolInfo> {
     let files = project.files(db);
     let files: Vec<_> = files.iter().copied().collect();
 
-    files
+    let mut found: Vec<WorkspaceSymbolInfo> = files
         .into_par_iter()
         .map_with_db(db, |db, file| {
             let symbols_for_file_span = tracing::debug_span!(
@@ -35,11 +36,27 @@ pub fn workspace_symbols(db: &dyn Db, query: &str) -> Vec<WorkspaceSymbolInfo> {
                 .map(|(_, symbol)| WorkspaceSymbolInfo {
                     symbol: symbol.to_owned(),
                     file,
+                    container: None,
                 })
                 .collect::<Vec<_>>()
         })
         .flat_map_iter(|symbols| symbols)
-        .collect()
+        .collect();
+
+    // a django project is made of things python has no symbol for — a route
+    // name, a template — and of classes python offers without saying what django
+    // does with them. both are added to the python answer rather than changing it
+    found.extend(
+        django_workspace_symbols(db, &query)
+            .into_iter()
+            .map(|django| WorkspaceSymbolInfo {
+                symbol: django.symbol,
+                file: django.file,
+                container: Some(django.container),
+            }),
+    );
+
+    found
 }
 
 /// A symbol found in the workspace, including the file it was found in.
@@ -49,6 +66,11 @@ pub struct WorkspaceSymbolInfo {
     pub symbol: SymbolInfo<'static>,
     /// The file containing the symbol
     pub file: File,
+    /// what kind of django thing this is, for a symbol django contributed
+    ///
+    /// `None` for everything python contributes, which is every symbol that was
+    /// ever answered before django was.
+    pub container: Option<&'static str>,
 }
 
 #[cfg(test)]
diff --git a/crates/ty_module_resolver/src/resolve.rs b/crates/ty_module_resolver/src/resolve.rs
index 79920e7c37..aa2f9c67ff 100644
--- a/crates/ty_module_resolver/src/resolve.rs
+++ b/crates/ty_module_resolver/src/resolve.rs
@@ -770,6 +770,18 @@ impl SearchPaths {
         }
     }
 
+    /// Returns the `site-packages` directories of the environment ty resolved.
+    ///
+    /// These are the one link back from the settings to the Python installation
+    /// they were discovered from, which is what lets a caller that has to *run*
+    /// something — rather than only resolve it — find the interpreter whose
+    /// packages ty is reading.
+    pub fn site_packages_paths(&self) -> impl Iterator<Item = &SystemPath> {
+        self.site_packages
+            .iter()
+            .filter_map(|path| path.as_system_path())
+    }
+
     /// Registers file roots for all non-dynamically discovered search paths.
     pub fn try_register_static_roots(&self, db: &dyn Db) {
         let files = db.files();
diff --git a/crates/ty_python_core/src/definition.rs b/crates/ty_python_core/src/definition.rs
index ea1cbbdb57..ce40e1731f 100644
--- a/crates/ty_python_core/src/definition.rs
+++ b/crates/ty_python_core/src/definition.rs
@@ -1005,6 +1005,13 @@ impl<'db> DefinitionKind<'db> {
         }
     }
 
+    pub const fn as_function(&self) -> Option<&AstNodeRef<ast::StmtFunctionDef>> {
+        match self {
+            DefinitionKind::Function(function) => Some(function),
+            _ => None,
+        }
+    }
+
     pub fn is_import(&self) -> bool {
         matches!(
             self,
diff --git a/crates/ty_server/src/capabilities.rs b/crates/ty_server/src/capabilities.rs
index fce472ab62..a7e413338b 100644
--- a/crates/ty_server/src/capabilities.rs
+++ b/crates/ty_server/src/capabilities.rs
@@ -52,19 +52,22 @@ impl std::fmt::Display for ResolvedClientCapabilities {
 #[derive(Clone, Copy, Debug, PartialEq)]
 pub(crate) enum SupportedCommand {
     Debug,
+    /// Run the project's `manage.py` with the given arguments.
+    RunManage,
 }
 
 impl SupportedCommand {
     /// Returns the identifier of the command.
-    const fn identifier(self) -> &'static str {
+    pub(crate) const fn identifier(self) -> &'static str {
         match self {
             SupportedCommand::Debug => "ty.printDebugInformation",
+            SupportedCommand::RunManage => "ty.runManageCommand",
         }
     }
 
     /// Returns all the commands that the server currently supports.
-    const fn all() -> [SupportedCommand; 1] {
-        [SupportedCommand::Debug]
+    const fn all() -> [SupportedCommand; 2] {
+        [SupportedCommand::Debug, SupportedCommand::RunManage]
     }
 }
 
@@ -74,6 +77,7 @@ impl FromStr for SupportedCommand {
     fn from_str(name: &str) -> anyhow::Result<Self, Self::Err> {
         Ok(match name {
             "ty.printDebugInformation" => Self::Debug,
+            "ty.runManageCommand" => Self::RunManage,
             _ => return Err(anyhow::anyhow!("Invalid command `{name}`")),
         })
     }
@@ -448,7 +452,12 @@ pub(crate) fn server_capabilities(
         document_highlight_provider: Some(true.into()),
         hover_provider: Some(true.into()),
         signature_help_provider: Some(SignatureHelpOptions {
-            trigger_characters: Some(vec!["(".to_string(), ",".to_string()]),
+            // `:` is here for django templates, where a filter's argument is
+            // written after one and nothing else opens an argument. LSP has no
+            // way to vary these per language, so python documents see the
+            // requests too — and turn them away, see
+            // `triggered_by_a_template_character`.
+            trigger_characters: Some(vec!["(".to_string(), ",".to_string(), ":".to_string()]),
             retrigger_characters: Some(vec![")".to_string()]),
             work_done_progress_options: WorkDoneProgressOptions::default(),
         }),
@@ -488,6 +497,14 @@ pub(crate) fn server_capabilities(
             ]),
             ..Default::default()
         }),
+        // every lens the server produces already carries its command: deciding
+        // that a lens exists at all is the same walk that works out what it would
+        // run, so there is nothing left for a `codeLens/resolve` to fill in and it
+        // is deliberately not offered
+        code_lens_provider: Some(types::CodeLensOptions {
+            resolve_provider: Some(false),
+            work_done_progress_options: WorkDoneProgressOptions::default(),
+        }),
         selection_range_provider: Some(true.into()),
         folding_range_provider: Some(true.into()),
         document_symbol_provider: Some(true.into()),
diff --git a/crates/ty_server/src/document/text_document.rs b/crates/ty_server/src/document/text_document.rs
index 0e4621fcdf..34f36cb61c 100644
--- a/crates/ty_server/src/document/text_document.rs
+++ b/crates/ty_server/src/document/text_document.rs
@@ -51,12 +51,20 @@ impl LanguageId {
     /// setups just call it `html`. That last case is why the path is consulted
     /// at all — a `.html` file inside a `templates` directory is a django
     /// template whatever the client chose to call it.
+    ///
+    /// A jinja id is deliberately turned away rather than taken as django. The
+    /// two languages read alike, but every template service here answers as
+    /// django, so a jinja document routed to them has its correct `{% set %}`,
+    /// `{% macro %}` or `|default("x")` reported as an error — a false positive
+    /// on correct code. We have no jinja support to offer, and [`Self::Other`] —
+    /// no template services at all — is the honest answer. It is answered
+    /// outright, ahead of the path fallback, because a client that says `jinja`
+    /// has settled the question that fallback exists to guess at.
     pub(crate) fn new(language_id: &LanguageKind, path: &AnySystemPath) -> Self {
         match language_id.as_str() {
             "python" | "by" => Self::Python,
-            "django-html" | "django-txt" | "htmldjango" | "jinja-html" | "django" => {
-                Self::DjangoTemplate
-            }
+            "django-html" | "django-txt" | "htmldjango" | "django" => Self::DjangoTemplate,
+            "jinja" | "jinja-html" | "jinja2" => Self::Other,
             _ => match path.as_system() {
                 Some(path) if ty_ide::is_django_template_path(path) => Self::DjangoTemplate,
                 _ => Self::Other,
@@ -184,12 +192,61 @@ impl TextDocument {
 
 #[cfg(test)]
 mod tests {
+    use crate::document::text_document::LanguageId;
     use crate::{PositionEncoding, TextDocument};
     use lsp_types::{
         LanguageKind, Position, TextDocumentContentChangeEvent, TextDocumentContentChangePartial,
         Uri,
     };
 
+    fn opened(uri: &str, language_id: &str) -> LanguageId {
+        TextDocument::new(
+            Uri::parse(uri).unwrap(),
+            String::new(),
+            0,
+            &LanguageKind::from(language_id.to_string()),
+        )
+        .language_id()
+    }
+
+    #[test]
+    fn the_editors_django_language_ids_are_django_templates() {
+        for id in ["django", "django-html", "django-txt", "htmldjango"] {
+            assert_eq!(
+                opened("file:///app/page.html", id),
+                LanguageId::DjangoTemplate,
+                "`{id}` is a django template"
+            );
+        }
+    }
+
+    #[test]
+    fn a_jinja_document_gets_no_template_services() {
+        // jinja is a different language that reads alike, and everything the
+        // template services answer with is django's — see `LanguageId::new`
+        for id in ["jinja", "jinja-html", "jinja2"] {
+            assert_eq!(
+                opened("file:///app/templates/page.html", id),
+                LanguageId::Other,
+                "`{id}` is turned away even where the path says django"
+            );
+        }
+
+        assert_eq!(
+            opened("file:///app/templates/page.jinja", "plaintext"),
+            LanguageId::Other
+        );
+    }
+
+    #[test]
+    fn an_html_file_under_templates_is_a_django_template_whatever_it_is_called() {
+        assert_eq!(
+            opened("file:///app/templates/page.html", "html"),
+            LanguageId::DjangoTemplate
+        );
+        assert_eq!(opened("file:///app/page.html", "html"), LanguageId::Other);
+    }
+
     #[test]
     fn redo_edit() {
         let mut document = TextDocument::new(
diff --git a/crates/ty_server/src/server/api.rs b/crates/ty_server/src/server/api.rs
index d1fc0e9fb6..a615a147eb 100644
--- a/crates/ty_server/src/server/api.rs
+++ b/crates/ty_server/src/server/api.rs
@@ -100,6 +100,9 @@ pub(super) fn request(req: server::Request) -> Task {
         requests::FoldingRangeRequestHandler::METHOD => background_document_request_task::<
             requests::FoldingRangeRequestHandler,
         >(req, BackgroundSchedule::Worker),
+        requests::CodeLensRequestHandler::METHOD => background_document_request_task::<
+            requests::CodeLensRequestHandler,
+        >(req, BackgroundSchedule::Worker),
         requests::DocumentSymbolRequestHandler::METHOD => background_document_request_task::<
             requests::DocumentSymbolRequestHandler,
         >(req, BackgroundSchedule::Worker),
diff --git a/crates/ty_server/src/server/api/requests.rs b/crates/ty_server/src/server/api/requests.rs
index 47ee0409bf..5d3d207892 100644
--- a/crates/ty_server/src/server/api/requests.rs
+++ b/crates/ty_server/src/server/api/requests.rs
@@ -15,6 +15,7 @@ module. For example, see `super::type_hierarchy`.
 mod call_hierarchy_incoming_calls;
 mod call_hierarchy_outgoing_calls;
 mod code_action;
+mod code_lens;
 mod completion;
 mod diagnostic;
 mod doc_highlights;
@@ -44,6 +45,7 @@ mod workspace_symbols;
 pub(super) use call_hierarchy_incoming_calls::CallHierarchyIncomingCallsRequestHandler;
 pub(super) use call_hierarchy_outgoing_calls::CallHierarchyOutgoingCallsRequestHandler;
 pub(super) use code_action::CodeActionRequestHandler;
+pub(super) use code_lens::CodeLensRequestHandler;
 pub(super) use completion::CompletionRequestHandler;
 pub(super) use diagnostic::DocumentDiagnosticRequestHandler;
 pub(super) use doc_highlights::DocumentHighlightRequestHandler;
diff --git a/crates/ty_server/src/server/api/requests/code_lens.rs b/crates/ty_server/src/server/api/requests/code_lens.rs
new file mode 100644
index 0000000000..196038fc46
--- /dev/null
+++ b/crates/ty_server/src/server/api/requests/code_lens.rs
@@ -0,0 +1,122 @@
+use std::borrow::Cow;
+
+use lsp_types::{CodeLens, CodeLensParams, CodeLensRequest, Uri};
+use ruff_db::files::FileRange;
+use ty_ide::{DjangoLensAction, django_python_code_lenses, django_template_code_lenses};
+use ty_project::ProjectDatabase;
+
+use crate::capabilities::SupportedCommand;
+use crate::document::{FileRangeExt, ToRangeExt};
+use crate::server::api::traits::{
+    BackgroundDocumentRequestHandler, RequestHandler, RetriableRequestHandler,
+};
+use crate::session::DocumentSnapshot;
+use crate::session::client::Client;
+
+/// The command a navigating lens asks the client to run.
+///
+/// LSP has no navigation command of its own, so a lens that goes somewhere has to
+/// name one the client already knows. This is the identifier VS Code registers and
+/// that the editors emulating its lenses — and rust-analyzer's, which is where the
+/// convention comes from — recognise. Its arguments are the document the lens is
+/// in, the position it sits at, and the locations to offer.
+const SHOW_REFERENCES_COMMAND: &str = "editor.action.showReferences";
+
+pub(crate) struct CodeLensRequestHandler;
+
+impl RequestHandler for CodeLensRequestHandler {
+    type RequestType = CodeLensRequest;
+}
+
+impl BackgroundDocumentRequestHandler for CodeLensRequestHandler {
+    fn document_uri(params: &CodeLensParams) -> Cow<'_, Uri> {
+        Cow::Borrowed(&params.text_document.uri)
+    }
+
+    fn run_with_snapshot(
+        db: &ProjectDatabase,
+        snapshot: &DocumentSnapshot,
+        _client: &Client,
+        _params: CodeLensParams,
+    ) -> crate::server::Result<Option<Vec<CodeLens>>> {
+        if snapshot
+            .workspace_settings()
+            .is_language_services_disabled()
+        {
+            return Ok(None);
+        }
+
+        let Some(file) = snapshot.to_notebook_or_file(db) else {
+            return Ok(None);
+        };
+
+        let lenses = if snapshot.is_django_template() {
+            django_template_code_lenses(db, file)
+        } else {
+            django_python_code_lenses(db, file)
+        };
+
+        let uri = snapshot.uri().clone();
+
+        let lenses: Vec<CodeLens> = lenses
+            .into_iter()
+            .filter_map(|lens| {
+                let range = lens
+                    .range
+                    .to_lsp_range(db, file, snapshot.encoding())?
+                    .local_range();
+
+                let command = match lens.action {
+                    DjangoLensAction::Run(arguments) => lsp_types::Command {
+                        title: lens.title,
+                        command: SupportedCommand::RunManage.identifier().to_string(),
+                        tooltip: None,
+                        arguments: Some(vec![serde_json::json!({
+                            "arguments": arguments,
+                        })]),
+                    },
+                    DjangoLensAction::Navigate(targets) => {
+                        let locations: Vec<lsp_types::Location> = targets
+                            .into_iter()
+                            .filter_map(|target| {
+                                FileRange::new(target.file, target.range)
+                                    .to_lsp_range(db, snapshot.encoding())?
+                                    .to_location()
+                            })
+                            .collect();
+
+                        // a lens that would navigate nowhere is worse than no lens
+                        if locations.is_empty() {
+                            return None;
+                        }
+
+                        lsp_types::Command {
+                            title: lens.title,
+                            command: SHOW_REFERENCES_COMMAND.to_string(),
+                            tooltip: None,
+                            arguments: Some(vec![
+                                serde_json::to_value(&uri).ok()?,
+                                serde_json::to_value(range.start).ok()?,
+                                serde_json::to_value(&locations).ok()?,
+                            ]),
+                        }
+                    }
+                };
+
+                Some(CodeLens {
+                    range,
+                    command: Some(command),
+                    data: None,
+                })
+            })
+            .collect();
+
+        if lenses.is_empty() {
+            Ok(None)
+        } else {
+            Ok(Some(lenses))
+        }
+    }
+}
+
+impl RetriableRequestHandler for CodeLensRequestHandler {}
diff --git a/crates/ty_server/src/server/api/requests/document_symbols.rs b/crates/ty_server/src/server/api/requests/document_symbols.rs
index 2959422461..578bf62885 100644
--- a/crates/ty_server/src/server/api/requests/document_symbols.rs
+++ b/crates/ty_server/src/server/api/requests/document_symbols.rs
@@ -89,7 +89,7 @@ impl BackgroundDocumentRequestHandler for DocumentSymbolRequestHandler {
             let lsp_symbols = symbols
                 .iter()
                 .filter_map(|(_, symbol)| {
-                    convert_to_lsp_symbol_information(db, file, symbol, snapshot.encoding())
+                    convert_to_lsp_symbol_information(db, file, symbol, None, snapshot.encoding())
                 })
                 .collect();
 
@@ -130,7 +130,7 @@ fn template_symbols(
 
     let lsp_symbols = flattened
         .into_iter()
-        .filter_map(|symbol| convert_to_lsp_symbol_information(db, file, symbol, encoding))
+        .filter_map(|symbol| convert_to_lsp_symbol_information(db, file, symbol, None, encoding))
         .collect();
 
     Some(lsp_types::DocumentSymbolResponse::SymbolInformationList(
diff --git a/crates/ty_server/src/server/api/requests/execute_command.rs b/crates/ty_server/src/server/api/requests/execute_command.rs
index c7ee7b2040..6f4c9d2462 100644
--- a/crates/ty_server/src/server/api/requests/execute_command.rs
+++ b/crates/ty_server/src/server/api/requests/execute_command.rs
@@ -7,11 +7,13 @@ use crate::session::Session;
 use crate::session::client::Client;
 use lsp_server::ErrorCode;
 use lsp_types::ExecuteCommandRequest;
-use lsp_types::{self as types};
+use lsp_types::{self as types, MessageType};
+use ruff_db::Db as _;
+use ruff_db::system::SystemPathBuf;
 use std::fmt::{self, Write};
 use std::str::FromStr;
 use ty_module_resolver::ModuleResolveMode;
-use ty_project::Db as _;
+use ty_project::{Db as _, ProjectDatabase};
 use ty_python_core::program::Program;
 
 pub(crate) struct ExecuteCommand;
@@ -23,7 +25,7 @@ impl RequestHandler for ExecuteCommand {
 impl SyncRequestHandler for ExecuteCommand {
     fn run(
         session: &mut Session,
-        _client: &Client,
+        client: &Client,
         params: types::ExecuteCommandParams,
     ) -> server::Result<Option<serde_json::Value>> {
         let command = SupportedCommand::from_str(&params.command)
@@ -33,10 +35,196 @@ impl SyncRequestHandler for ExecuteCommand {
             SupportedCommand::Debug => Ok(Some(serde_json::Value::String(
                 debug_information(session).with_failure_code(ErrorCode::InternalError)?,
             ))),
+            SupportedCommand::RunManage => {
+                let arguments: ManageArguments = params
+                    .arguments
+                    .into_iter()
+                    .flatten()
+                    .next()
+                    .ok_or_else(|| anyhow::anyhow!("`{}` takes one argument", params.command))
+                    .and_then(|argument| Ok(serde_json::from_value(argument)?))
+                    .with_failure_code(ErrorCode::InvalidParams)?;
+
+                run_manage(session, client, &arguments.arguments)
+                    .with_failure_code(ErrorCode::InvalidParams)?;
+
+                Ok(None)
+            }
         }
     }
 }
 
+/// What a `ty.runManageCommand` is asked to run.
+#[derive(Debug, serde::Deserialize)]
+struct ManageArguments {
+    /// The arguments to `manage.py`, the subcommand first.
+    arguments: Vec<String>,
+}
+
+/// Django management commands that must not be run this way.
+///
+/// A command the server spawns has no terminal: its output is a log the client
+/// appends to, there is no stdin to type into and no way to interrupt it. That is
+/// fine for a command that runs and finishes, and wrong for one that expects to
+/// own a terminal — a `runserver` would run until the editor was closed with no
+/// way to stop it, and a `shell` would sit waiting for input that can never
+/// arrive. Neither is offered by any lens; this is what keeps a client that asks
+/// for one anyway from being left with a process it cannot reach. The refusal
+/// hands back the command line instead, so a client that wants to open a terminal
+/// of its own has what to put in it.
+const TERMINAL_COMMANDS: &[&str] = &["runserver", "shell", "dbshell", "createsuperuser"];
+
+/// The management commands a lens offers, and so the only ones this will run.
+///
+/// Spawning a process is the one thing the server does that reaches outside
+/// itself, so what it will spawn is stated rather than inferred: a command
+/// nothing offered is refused. Django's own set includes `flush` and
+/// `sqlflush`, and a project can add whatever it likes to it, so "anything but
+/// the few we know are wrong" is a much larger promise than this needs to make.
+const OFFERED_COMMANDS: &[&str] = &["test", "makemigrations", "migrate", "sqlmigrate"];
+
+/// Runs the project's `manage.py`, reporting through `window/logMessage`.
+///
+/// The process is spawned on a thread of its own so that a command that takes a
+/// while — a test suite is the whole point of this — doesn't stop the server
+/// answering anything else in the meantime.
+fn run_manage(session: &Session, client: &Client, arguments: &[String]) -> crate::Result<()> {
+    let Some(subcommand) = arguments.first() else {
+        return Err(anyhow::anyhow!("no management command was named"));
+    };
+
+    // this is a refusal about the command itself, so it does not wait on finding
+    // the project's `manage.py` or its interpreter first
+    if TERMINAL_COMMANDS.contains(&subcommand.as_str()) {
+        return Err(anyhow::anyhow!(
+            "`manage.py {subcommand}` needs a terminal, which the server cannot give it. \
+             Run it yourself: `manage.py {}`",
+            arguments.join(" "),
+        ));
+    }
+
+    if !OFFERED_COMMANDS.contains(&subcommand.as_str()) {
+        return Err(anyhow::anyhow!(
+            "the server only runs the management commands it offers a lens for, \
+             and `{subcommand}` is not one of them. Run it yourself: `manage.py {}`",
+            arguments.join(" "),
+        ));
+    }
+
+    let (manage, interpreter) = session
+        .project_dbs()
+        .find_map(|db| {
+            let manage = ty_ide::django_manage_script(db)?
+                .path(db)
+                .as_system_path()?
+                .to_path_buf();
+
+            Some((manage, interpreter(db)))
+        })
+        .ok_or_else(|| anyhow::anyhow!("this project has no `manage.py`"))?;
+
+    let interpreter = interpreter.ok_or_else(|| {
+        anyhow::anyhow!(
+            "no python interpreter could be found for this project, \
+             so `manage.py` cannot be run"
+        )
+    })?;
+
+    // django resolves its settings, its apps and its templates relative to the
+    // directory `manage.py` sits in, which is why it is run from there rather than
+    // from wherever the editor happens to have been started
+    let working_directory = manage
+        .parent()
+        .ok_or_else(|| anyhow::anyhow!("`{manage}` is not in a directory"))?
+        .to_path_buf();
+
+    let mut process = std::process::Command::new(interpreter.as_std_path());
+    process
+        .arg(manage.as_std_path())
+        .args(arguments)
+        .current_dir(working_directory.as_std_path())
+        .stdout(std::process::Stdio::piped())
+        .stderr(std::process::Stdio::piped());
+
+    let line = format!("manage.py {}", arguments.join(" "));
+    let client = client.clone();
+
+    std::thread::Builder::new()
+        .name("ty:manage".to_string())
+        .spawn(move || {
+            log(&client, MessageType::Info, format!("running {line}"));
+
+            match process.output() {
+                Ok(output) => {
+                    // django's test runner and most of its commands report on
+                    // stderr, so both streams are the answer rather than one
+                    for stream in [&output.stdout, &output.stderr] {
+                        let text = String::from_utf8_lossy(stream);
+                        if !text.trim().is_empty() {
+                            log(&client, MessageType::Info, text.trim_end().to_string());
+                        }
+                    }
+
+                    let (kind, outcome) = if output.status.success() {
+                        (MessageType::Info, "succeeded".to_string())
+                    } else {
+                        (MessageType::Error, format!("failed ({})", output.status))
+                    };
+                    log(&client, kind, format!("{line} {outcome}"));
+                }
+                Err(error) => log(
+                    &client,
+                    MessageType::Error,
+                    format!("{line} could not be started: {error}"),
+                ),
+            }
+        })?;
+
+    Ok(())
+}
+
+fn log(client: &Client, kind: MessageType, message: String) {
+    client.send_notification::<lsp_types::LogMessageNotification>(lsp_types::LogMessageParams {
+        kind,
+        message,
+    });
+}
+
+/// The interpreter of the environment whose packages the project is checked against.
+///
+/// ty resolves a python environment to find the project's third-party packages, and
+/// its `site-packages` is the one link back to the installation it came from — which
+/// is the installation that has django in it, and so the only one able to run
+/// `manage.py`. The layout is walked upwards and the candidate is *checked to
+/// exist* rather than assumed, so an environment shaped like nothing here expects
+/// yields no interpreter instead of an unrunnable path.
+fn interpreter(db: &ProjectDatabase) -> Option<SystemPathBuf> {
+    // `<prefix>/lib/python3.13/site-packages` on unix, `<prefix>/Lib/site-packages`
+    // on windows: three hops up covers the deeper of the two, and every shallower
+    // ancestor is tried on the way
+    const MAX_PREFIX_DEPTH: usize = 3;
+
+    const EXECUTABLES: &[&str] = &[
+        "bin/python3",
+        "bin/python",
+        "Scripts/python.exe",
+        "python.exe",
+    ];
+
+    let system = db.system();
+
+    Program::get(db)
+        .search_paths(db)
+        .site_packages_paths()
+        .flat_map(|site_packages| site_packages.ancestors().take(MAX_PREFIX_DEPTH + 1))
+        .find_map(|prefix| {
+            EXECUTABLES
+                .iter()
+                .map(|executable| prefix.join(executable))
+                .find(|candidate| system.is_file(candidate))
+        })
+}
+
 /// Returns a string with detailed memory usage.
 fn debug_information(session: &Session) -> crate::Result<String> {
     let mut buffer = String::new();
diff --git a/crates/ty_server/src/server/api/requests/inlay_hints.rs b/crates/ty_server/src/server/api/requests/inlay_hints.rs
index 3339afbf66..1a7b84632c 100644
--- a/crates/ty_server/src/server/api/requests/inlay_hints.rs
+++ b/crates/ty_server/src/server/api/requests/inlay_hints.rs
@@ -4,7 +4,10 @@ use std::time::Instant;
 use lsp_types::InlayHintRequest;
 use lsp_types::{InlayHintParams, Uri};
 use ruff_db::files::File;
-use ty_ide::{InlayHintKind, InlayHintLabel, InlayHintTextEdit, inlay_hints};
+use ty_ide::{
+    InlayHintKind, InlayHintLabel, InlayHintTextEdit, TemplateInlayHint, TemplateInlayHintKind,
+    django_template_inlay_hints, inlay_hints,
+};
 use ty_project::ProjectDatabase;
 
 use crate::PositionEncoding;
@@ -51,6 +54,16 @@ impl BackgroundDocumentRequestHandler for InlayHintRequestHandler {
             return Ok(None);
         };
 
+        if snapshot.is_django_template() {
+            let hints =
+                django_template_inlay_hints(db, file, range, workspace_settings.inlay_hints())
+                    .into_iter()
+                    .filter_map(|hint| template_inlay_hint(hint, db, file, snapshot.encoding()))
+                    .collect();
+
+            return Ok(Some(hints));
+        }
+
         let inlay_hints = inlay_hints(db, file, range, workspace_settings.inlay_hints());
 
         let inlay_hints: Vec<lsp_types::InlayHint> = inlay_hints
@@ -91,6 +104,35 @@ impl BackgroundDocumentRequestHandler for InlayHintRequestHandler {
 
 impl RetriableRequestHandler for InlayHintRequestHandler {}
 
+/// one django template hint, as the client shows it
+///
+/// a resolved template's path is neither a type nor a parameter, and LSP has no
+/// kind that fits it, so it is sent with none — which is what leaves a client's
+/// type-specific styling for the hints that really are types.
+fn template_inlay_hint(
+    hint: TemplateInlayHint,
+    db: &ProjectDatabase,
+    file: File,
+    encoding: PositionEncoding,
+) -> Option<lsp_types::InlayHint> {
+    Some(lsp_types::InlayHint {
+        position: hint
+            .position
+            .to_lsp_position(db, file, encoding)?
+            .local_position(),
+        label: lsp_types::Label::String(hint.label),
+        kind: match hint.kind {
+            TemplateInlayHintKind::Type => Some(lsp_types::InlayHintKind::Type),
+            TemplateInlayHintKind::Template => None,
+        },
+        tooltip: None,
+        padding_left: None,
+        padding_right: None,
+        data: None,
+        text_edits: None,
+    })
+}
+
 fn inlay_hint_kind(inlay_hint_kind: &InlayHintKind) -> lsp_types::InlayHintKind {
     match inlay_hint_kind {
         InlayHintKind::Type
diff --git a/crates/ty_server/src/server/api/requests/signature_help.rs b/crates/ty_server/src/server/api/requests/signature_help.rs
index 7572c3b69c..2a200f7830 100644
--- a/crates/ty_server/src/server/api/requests/signature_help.rs
+++ b/crates/ty_server/src/server/api/requests/signature_help.rs
@@ -11,7 +11,7 @@ use lsp_types::{
     Documentation, ParameterInformation, ParameterInformationLabel, SignatureHelp,
     SignatureHelpParams, SignatureInformation, Uri,
 };
-use ty_ide::signature_help;
+use ty_ide::{TemplateSignature, django_template_signature_help, signature_help};
 use ty_project::ProjectDatabase;
 
 pub(crate) struct SignatureHelpRequestHandler;
@@ -51,6 +51,19 @@ impl BackgroundDocumentRequestHandler for SignatureHelpRequestHandler {
             return Ok(None);
         };
 
+        if snapshot.is_django_template() {
+            return Ok(django_template_signature_help(db, file, offset).map(template_signature));
+        }
+
+        if triggered_by_a_template_character(&params) {
+            // `:` is registered as a trigger character for the sake of django
+            // templates, and LSP has no way to register it for one language
+            // only. python gets the requests too, and a popup the moment the
+            // user annotates a parameter or opens a slice is not what they
+            // asked for.
+            return Ok(None);
+        }
+
         // Extract signature help capabilities from the client
         let resolved_capabilities = snapshot.resolved_client_capabilities();
 
@@ -151,3 +164,44 @@ impl BackgroundDocumentRequestHandler for SignatureHelpRequestHandler {
 }
 
 impl RetriableRequestHandler for SignatureHelpRequestHandler {}
+
+/// The trigger character registered for django templates alone, listed in
+/// `capabilities`, where the reason it is registered at all is spelled out.
+const TEMPLATE_TRIGGER_CHARACTER: &str = ":";
+
+/// Whether this request was triggered by typing a character that opens no
+/// argument outside a django template.
+fn triggered_by_a_template_character(params: &SignatureHelpParams) -> bool {
+    params.context.as_ref().is_some_and(|context| {
+        context.trigger_kind == lsp_types::SignatureHelpTriggerKind::TriggerCharacter
+            && context.trigger_character.as_deref() == Some(TEMPLATE_TRIGGER_CHARACTER)
+    })
+}
+
+/// a django filter's argument, as the one signature the client is offered
+///
+/// the parameter is written as a plain string rather than as an offset into the
+/// label: a template's signature is short enough that a client can find it, and a
+/// label offset would have to be re-encoded for the client's position encoding.
+fn template_signature(signature: TemplateSignature) -> SignatureHelp {
+    let parameters: Vec<_> = signature
+        .parameter
+        .into_iter()
+        .map(|parameter| ParameterInformation {
+            label: ParameterInformationLabel::String(parameter),
+            documentation: None,
+        })
+        .collect();
+    let active_parameter = (!parameters.is_empty()).then_some(ActiveParameter::Int(0));
+
+    SignatureHelp {
+        signatures: vec![SignatureInformation {
+            label: signature.label,
+            documentation: signature.documentation.map(Documentation::String),
+            parameters: Some(parameters),
+            active_parameter,
+        }],
+        active_signature: Some(0),
+        active_parameter,
+    }
+}
diff --git a/crates/ty_server/src/server/api/requests/workspace_symbols.rs b/crates/ty_server/src/server/api/requests/workspace_symbols.rs
index 0bbb04cbe9..75f03f988b 100644
--- a/crates/ty_server/src/server/api/requests/workspace_symbols.rs
+++ b/crates/ty_server/src/server/api/requests/workspace_symbols.rs
@@ -37,12 +37,17 @@ impl BackgroundRequestHandler for WorkspaceSymbolRequestHandler {
 
             // Convert to LSP SymbolInformation
             for workspace_symbol_info in workspace_symbol_infos {
-                let WorkspaceSymbolInfo { symbol, file } = workspace_symbol_info;
+                let WorkspaceSymbolInfo {
+                    symbol,
+                    file,
+                    container,
+                } = workspace_symbol_info;
 
                 // Get position encoding from session
                 let encoding = snapshot.position_encoding();
 
-                let Some(symbol) = convert_to_lsp_symbol_information(db, file, symbol, encoding)
+                let Some(symbol) =
+                    convert_to_lsp_symbol_information(db, file, symbol, container, encoding)
                 else {
                     tracing::debug!(
                         "Failed to convert symbol '{}' to LSP symbol information",
diff --git a/crates/ty_server/src/server/api/symbols.rs b/crates/ty_server/src/server/api/symbols.rs
index ba6d478cec..06f7e87da4 100644
--- a/crates/ty_server/src/server/api/symbols.rs
+++ b/crates/ty_server/src/server/api/symbols.rs
@@ -27,12 +27,16 @@ pub(crate) fn convert_symbol_kind(kind: ty_ide::SymbolKind) -> SymbolKind {
 
 /// Convert a `ty_ide` `SymbolInfo` to LSP `SymbolInformation`
 ///
+/// `container` is what the symbol belongs to, which is how a django route or
+/// model says what it is beside the python symbol of the same name.
+///
 /// Returns `None` if the symbol's range cannot be converted to a location
 /// (e.g., if the file cannot be converted to a URI).
 pub(crate) fn convert_to_lsp_symbol_information(
     db: &dyn Db,
     file: ruff_db::files::File,
     symbol: SymbolInfo<'_>,
+    container: Option<&str>,
     encoding: PositionEncoding,
 ) -> Option<SymbolInformation> {
     let symbol_kind = convert_symbol_kind(symbol.kind);
@@ -45,7 +49,7 @@ pub(crate) fn convert_to_lsp_symbol_information(
             name: symbol.name.into_owned(),
             kind: symbol_kind,
             tags: None,
-            container_name: None,
+            container_name: container.map(str::to_string),
         },
         #[allow(deprecated)]
         deprecated: None,
diff --git a/crates/ty_server/src/session/options.rs b/crates/ty_server/src/session/options.rs
index e6fb91c482..d38933cf53 100644
--- a/crates/ty_server/src/session/options.rs
+++ b/crates/ty_server/src/session/options.rs
@@ -373,6 +373,8 @@ pub struct InlayHintOptions {
     implicit_parameters: Option<bool>,
     lambda_parameter_types: Option<bool>,
     implicit_arguments: Option<bool>,
+    template_binding_types: Option<bool>,
+    resolved_templates: Option<bool>,
 }
 
 impl InlayHintOptions {
@@ -391,6 +393,8 @@ impl InlayHintOptions {
             implicit_parameters: self.implicit_parameters.unwrap_or(true),
             lambda_parameter_types: self.lambda_parameter_types.unwrap_or(true),
             implicit_arguments: self.implicit_arguments.unwrap_or(true),
+            template_binding_types: self.template_binding_types.unwrap_or(true),
+            resolved_templates: self.resolved_templates.unwrap_or(true),
         }
     }
 }
diff --git a/crates/ty_server/tests/e2e/django_templates.rs b/crates/ty_server/tests/e2e/django_templates.rs
index 8abbfca8d0..40cf986689 100644
--- a/crates/ty_server/tests/e2e/django_templates.rs
+++ b/crates/ty_server/tests/e2e/django_templates.rs
@@ -802,3 +802,380 @@ fn a_python_symbols_references_are_found_the_way_they_always_were() -> Result<()
 
     Ok(())
 }
+
+const SHELF_VIEWS: &str = "\
+from blog.models import Book
+
+
+def shelf(request):
+    return render(request, 'blog/shelf.html', {'shelf': [Book()]})
+";
+
+const EXTRAS: &str = "\
+from django import template
+
+register = template.Library()
+
+
+@register.filter
+def shout(value, suffix: str):
+    'shouts it.'
+    return value
+";
+
+const CARD: &str = "{{ book.title }}\n";
+
+/// a project whose view renders a list and whose app registers a filter taking an
+/// argument — neither of which the smaller fixture above has
+fn shelf_server(template: &str) -> Result<TestServer> {
+    let mut server = TestServerBuilder::new()?
+        .with_workspace(SystemPath::new("src"), None)?
+        .with_file(SystemPath::new("src/blog/models.py"), MODELS)?
+        .with_file(SystemPath::new("src/blog/views.py"), SHELF_VIEWS)?
+        .with_file(
+            SystemPath::new("src/blog/templatetags/blog_extras.py"),
+            EXTRAS,
+        )?
+        .with_file(SystemPath::new("src/blog/templates/blog/card.html"), CARD)?
+        .with_file(
+            SystemPath::new("src/blog/templates/blog/shelf.html"),
+            template,
+        )?
+        .enable_inlay_hints(true)
+        .build()
+        .wait_until_workspaces_are_initialized();
+
+    server.open_text_document_as(
+        SystemPath::new("src/blog/templates/blog/shelf.html"),
+        template,
+        1,
+        LanguageKind::new("django-html"),
+    );
+
+    Ok(server)
+}
+
+fn shelf_uri(server: &TestServer) -> lsp_types::Uri {
+    server.file_uri(SystemPath::new("src/blog/templates/blog/shelf.html"))
+}
+
+#[test]
+fn a_template_offers_a_project_filters_argument_as_its_signature() -> Result<()> {
+    let mut server = shelf_server("{{ book.title|shout:\"\" }}\n")?;
+    let uri = shelf_uri(&server);
+
+    let help = server
+        .signature_help_request(&uri, Position::new(0, 21))
+        .expect("a signature");
+    let signature = help.signatures.first().expect("one signature");
+
+    assert_eq!(signature.label, "|shout:suffix: str");
+    assert_eq!(
+        signature.documentation,
+        Some(lsp_types::Documentation::String("shouts it.".to_string()))
+    );
+
+    Ok(())
+}
+
+#[test]
+fn a_template_offers_a_django_filters_documentation_as_its_signature() -> Result<()> {
+    // nothing installs django here, so the builtin table is all there is — and
+    // what a filter is documented to do is still more than the template says
+    let mut server = server("{{ book.title|date:\"\" }}\n")?;
+    let uri = template_uri(&server);
+
+    let help = server
+        .signature_help_request(&uri, Position::new(0, 20))
+        .expect("a signature");
+    let signature = help.signatures.first().expect("one signature");
+
+    assert_eq!(signature.label, "|date");
+    assert_eq!(
+        signature.documentation,
+        Some(lsp_types::Documentation::String(
+            "formats a date with the given format string.".to_string()
+        ))
+    );
+
+    Ok(())
+}
+
+#[test]
+fn a_template_position_that_is_not_a_filter_argument_offers_no_signature() -> Result<()> {
+    let mut server = server("{{ book.title }}\n")?;
+    let uri = template_uri(&server);
+
+    assert!(
+        server
+            .signature_help_request(&uri, Position::new(0, 10))
+            .is_none()
+    );
+
+    Ok(())
+}
+
+/// a signature help request as the client sends one after the user typed `:`
+fn colon_triggered_signature_help(
+    server: &mut TestServer,
+    uri: &lsp_types::Uri,
+    position: Position,
+) -> Option<lsp_types::SignatureHelp> {
+    server.send_request_await::<lsp_types::SignatureHelpRequest>(lsp_types::SignatureHelpParams {
+        text_document_position_params: TextDocumentPositionParams {
+            text_document: TextDocumentIdentifier { uri: uri.clone() },
+            position,
+        },
+        work_done_progress_params: lsp_types::WorkDoneProgressParams::default(),
+        context: Some(lsp_types::SignatureHelpContext {
+            trigger_kind: lsp_types::SignatureHelpTriggerKind::TriggerCharacter,
+            trigger_character: Some(":".to_string()),
+            is_retrigger: false,
+            active_signature_help: None,
+        }),
+    })
+}
+
+#[test]
+fn a_colon_is_what_opens_a_filter_argument_and_triggers_the_request() -> Result<()> {
+    let mut server = shelf_server("{{ book.title|shout: }}\n")?;
+    let uri = shelf_uri(&server);
+
+    let help = colon_triggered_signature_help(&mut server, &uri, Position::new(0, 20))
+        .expect("a signature");
+
+    assert_eq!(help.signatures[0].label, "|shout:suffix: str");
+
+    Ok(())
+}
+
+#[test]
+fn a_colon_typed_in_python_is_not_a_filter_argument() -> Result<()> {
+    // `:` is a trigger character for the sake of templates alone, and LSP has no
+    // way to register it for one language only
+    let mut server = shelf_server("{{ book.title }}\n")?;
+    let views = SystemPath::new("src/blog/views.py");
+    server.open_text_document(views, SHELF_VIEWS, 1);
+    let uri = server.file_uri(views);
+
+    assert!(colon_triggered_signature_help(&mut server, &uri, Position::new(4, 45)).is_none());
+
+    Ok(())
+}
+
+#[test]
+fn a_template_hints_a_loop_binding_and_the_file_an_include_resolves_to() -> Result<()> {
+    let mut server =
+        shelf_server("{% for book in shelf %}{% include 'blog/card.html' %}{% endfor %}\n")?;
+
+    let hints = server
+        .inlay_hints_request(
+            SystemPath::new("src/blog/templates/blog/shelf.html"),
+            lsp_types::Range::new(Position::new(0, 0), Position::new(1, 0)),
+        )
+        .expect("hints");
+
+    let rendered: Vec<_> = hints
+        .iter()
+        .map(|hint| match &hint.label {
+            lsp_types::Label::String(label) => format!("{:?} {label}", hint.position.character),
+            parts @ lsp_types::Label::InlayHintLabelPartList(_) => format!("{parts:?}"),
+        })
+        .collect();
+
+    assert_eq!(
+        rendered,
+        ["11 : Book", "50  → blog/templates/blog/card.html"]
+    );
+
+    Ok(())
+}
+
+#[test]
+fn a_template_is_never_hinted_as_python() -> Result<()> {
+    // the python hints would need the template parsed as python; a template that
+    // says nothing django knows says nothing at all
+    let mut server = shelf_server("<p>a = 1</p>\n")?;
+
+    assert_eq!(
+        server.inlay_hints_request(
+            SystemPath::new("src/blog/templates/blog/shelf.html"),
+            lsp_types::Range::new(Position::new(0, 0), Position::new(1, 0)),
+        ),
+        Some(Vec::new())
+    );
+
+    Ok(())
+}
+
+/// what a lens says and what it would do, as `title -> command(arguments)`
+///
+/// a run lens carries its `manage.py` arguments and a navigating one carries the
+/// locations it offers, so the two render differently on purpose.
+fn code_lenses(server: &mut TestServer, path: &SystemPath) -> Vec<String> {
+    let lenses = server
+        .send_request_await::<lsp_types::CodeLensRequest>(lsp_types::CodeLensParams {
+            text_document: TextDocumentIdentifier {
+                uri: server.file_uri(path),
+            },
+            work_done_progress_params: lsp_types::WorkDoneProgressParams::default(),
+            partial_result_params: lsp_types::PartialResultParams::default(),
+        })
+        .unwrap_or_default();
+
+    lenses
+        .iter()
+        .map(|lens| {
+            let command = lens.command.as_ref().expect("a lens to carry its command");
+            let arguments = command.arguments.clone().unwrap_or_default();
+
+            let rendered = if command.command == "ty.runManageCommand" {
+                let arguments: Vec<String> = arguments
+                    .first()
+                    .and_then(|argument| argument.get("arguments").cloned())
+                    .and_then(|arguments| serde_json::from_value(arguments).ok())
+                    .unwrap_or_default();
+                format!("manage.py {}", arguments.join(" "))
+            } else {
+                let locations: Vec<lsp_types::Location> = arguments
+                    .get(2)
+                    .and_then(|argument| serde_json::from_value(argument.clone()).ok())
+                    .unwrap_or_default();
+                let rendered: Vec<String> = locations
+                    .iter()
+                    .map(|location| {
+                        format!("{}:{}", relative(&location.uri), location.range.start.line)
+                    })
+                    .collect();
+                format!("{} {}", command.command, rendered.join(", "))
+            };
+
+            format!("{} -> {rendered}", command.title)
+        })
+        .collect()
+}
+
+/// the python modules the runnable lenses are asked about
+///
+/// django's own `TestCase` is written out because a test class is recognised by
+/// the base chain it reaches, and there is no installed django here for it to
+/// reach otherwise.
+const RUNNABLE_SOURCES: &[(&str, &str)] = &[
+    ("src/django/__init__.py", ""),
+    (
+        "src/django/test/__init__.py",
+        "import unittest\n\n\nclass TestCase(unittest.TestCase):\n    pass\n",
+    ),
+    (
+        "src/blog/tests.py",
+        "from django.test import TestCase\n\n\nclass BookTest(TestCase):\n    def setUp(self):\n        pass\n\n    def test_detail(self):\n        pass\n",
+    ),
+    ("src/blog/plain.py", "value = 1\n"),
+];
+
+/// the whole project, plus the python modules a runnable lens applies to
+fn runnable_project() -> Result<TestServer> {
+    let mut builder = TestServerBuilder::new()?
+        .with_workspace(SystemPath::new("src"), None)?
+        .with_file(
+            SystemPath::new("src/manage.py"),
+            "import os\n\nos.environ.setdefault('DJANGO_SETTINGS_MODULE', 'project.settings')\n",
+        )?
+        .with_file(SystemPath::new("src/project/__init__.py"), "")?
+        .with_file(
+            SystemPath::new("src/project/settings.py"),
+            "INSTALLED_APPS = ['blog']\n\nTEMPLATES = [{'DIRS': [], 'APP_DIRS': True, 'OPTIONS': {}}]\n",
+        )?
+        .with_file(SystemPath::new("src/blog/__init__.py"), "")?;
+
+    for (path, contents) in RUNNABLE_SOURCES {
+        builder = builder.with_file(SystemPath::new(path), contents)?;
+    }
+
+    let mut server = builder.build().wait_until_workspaces_are_initialized();
+
+    for (path, contents) in RUNNABLE_SOURCES {
+        server.open_text_document(SystemPath::new(path), contents, 1);
+    }
+
+    Ok(server)
+}
+
+#[test]
+fn a_template_names_the_view_that_renders_it() -> Result<()> {
+    let mut server = whole_project(&[("src/blog/templates/blog/post.html", "<p>a</p>\n")])?;
+
+    assert_eq!(
+        code_lenses(
+            &mut server,
+            SystemPath::new("src/blog/templates/blog/post.html")
+        ),
+        ["rendered by blog.views.post -> editor.action.showReferences blog/views.py:4"]
+    );
+
+    Ok(())
+}
+
+#[test]
+fn a_template_nothing_renders_has_no_lens() -> Result<()> {
+    let mut server = whole_project(&[("src/blog/templates/blog/orphan.html", "<p>a</p>\n")])?;
+
+    assert!(
+        code_lenses(
+            &mut server,
+            SystemPath::new("src/blog/templates/blog/orphan.html")
+        )
+        .is_empty()
+    );
+
+    Ok(())
+}
+
+#[test]
+fn a_test_module_offers_the_management_command_that_runs_it() -> Result<()> {
+    let mut server = runnable_project()?;
+
+    assert_eq!(
+        code_lenses(&mut server, SystemPath::new("src/blog/tests.py")),
+        [
+            "run BookTest -> manage.py test blog.tests.BookTest",
+            "run test -> manage.py test blog.tests.BookTest.test_detail",
+        ]
+    );
+
+    Ok(())
+}
+
+#[test]
+fn an_ordinary_python_module_of_a_django_project_has_no_lens() -> Result<()> {
+    let mut server = runnable_project()?;
+
+    assert!(code_lenses(&mut server, SystemPath::new("src/blog/plain.py")).is_empty());
+
+    Ok(())
+}
+
+#[test]
+fn a_management_command_that_wants_a_terminal_is_refused_rather_than_spawned() -> Result<()> {
+    // a `runserver` the server spawned would run until the editor was closed with
+    // nothing able to stop it, so it is turned away instead
+    let mut server = runnable_project()?;
+
+    let id =
+        server.send_request::<lsp_types::ExecuteCommandRequest>(lsp_types::ExecuteCommandParams {
+            command: "ty.runManageCommand".to_string(),
+            arguments: Some(vec![serde_json::json!({"arguments": ["runserver"]})]),
+            work_done_progress_params: lsp_types::WorkDoneProgressParams::default(),
+        });
+
+    let failure = server
+        .try_await_response::<lsp_types::ExecuteCommandRequest>(&id, None)
+        .expect_err("a refusal rather than a process nothing could stop");
+
+    assert!(
+        format!("{failure}").contains("needs a terminal"),
+        "got {failure}"
+    );
+
+    Ok(())
+}
diff --git a/crates/ty_server/tests/e2e/snapshots/e2e__commands__debug_command.snap b/crates/ty_server/tests/e2e/snapshots/e2e__commands__debug_command.snap
index 517c4044ad..67ac4118f6 100644
--- a/crates/ty_server/tests/e2e/snapshots/e2e__commands__debug_command.snap
+++ b/crates/ty_server/tests/e2e/snapshots/e2e__commands__debug_command.snap
@@ -30,6 +30,8 @@ Settings: WorkspaceSettings {
         implicit_parameters: true,
         lambda_parameter_types: true,
         implicit_arguments: true,
+        template_binding_types: true,
+        resolved_templates: true,
     },
     completions: CompletionSettings {
         auto_import: true,
diff --git a/crates/ty_server/tests/e2e/snapshots/e2e__initialize__initialization.snap b/crates/ty_server/tests/e2e/snapshots/e2e__initialize__initialization.snap
index 58cd8e2ffd..0ee8a9bf79 100644
--- a/crates/ty_server/tests/e2e/snapshots/e2e__initialize__initialization.snap
+++ b/crates/ty_server/tests/e2e/snapshots/e2e__initialize__initialization.snap
@@ -38,7 +38,8 @@ expression: initialization_result
     "signatureHelpProvider": {
       "triggerCharacters": [
         "(",
-        ","
+        ",",
+        ":"
       ],
       "retriggerCharacters": [
         ")"
@@ -55,6 +56,9 @@ expression: initialization_result
         "quickfix"
       ]
     },
+    "codeLensProvider": {
+      "resolveProvider": false
+    },
     "workspaceSymbolProvider": true,
     "renameProvider": {
       "prepareProvider": true
@@ -63,7 +67,8 @@ expression: initialization_result
     "selectionRangeProvider": true,
     "executeCommandProvider": {
       "commands": [
-        "ty.printDebugInformation"
+        "ty.printDebugInformation",
+        "ty.runManageCommand"
       ],
       "workDoneProgress": false
     },
diff --git a/crates/ty_server/tests/e2e/snapshots/e2e__initialize__initialization_with_workspace.snap b/crates/ty_server/tests/e2e/snapshots/e2e__initialize__initialization_with_workspace.snap
index 58cd8e2ffd..0ee8a9bf79 100644
--- a/crates/ty_server/tests/e2e/snapshots/e2e__initialize__initialization_with_workspace.snap
+++ b/crates/ty_server/tests/e2e/snapshots/e2e__initialize__initialization_with_workspace.snap
@@ -38,7 +38,8 @@ expression: initialization_result
     "signatureHelpProvider": {
       "triggerCharacters": [
         "(",
-        ","
+        ",",
+        ":"
       ],
       "retriggerCharacters": [
         ")"
@@ -55,6 +56,9 @@ expression: initialization_result
         "quickfix"
       ]
     },
+    "codeLensProvider": {
+      "resolveProvider": false
+    },
     "workspaceSymbolProvider": true,
     "renameProvider": {
       "prepareProvider": true
@@ -63,7 +67,8 @@ expression: initialization_result
     "selectionRangeProvider": true,
     "executeCommandProvider": {
       "commands": [
-        "ty.printDebugInformation"
+        "ty.printDebugInformation",
+        "ty.runManageCommand"
       ],
       "workDoneProgress": false
     },
diff --git a/docs/basedpython/frameworks/django-templates.md b/docs/basedpython/frameworks/django-templates.md
index 0a69b7752b..2203971281 100644
--- a/docs/basedpython/frameworks/django-templates.md
+++ b/docs/basedpython/frameworks/django-templates.md
@@ -64,7 +64,25 @@ hovering says what the thing under the caret is: a variable or a path segment as
 
 a template's `{% block %}`s and `{% partialdef %}`s are its outline, nested as they nest, and every block tag folds.
 
-**no diagnostics.** templates are never type-checked — an unknown variable or a misspelled filter is not reported, it just doesn't complete.
+### signature help
+
+a filter's argument is the one thing a template writes that nothing beside it explains. with the caret after the `:`, `{{ value|date:"‸" }}` says what the filter takes: the registered function's second parameter, read from the project's own filters and from django's own wherever django itself can be read, together with what the filter is documented to do.
+
+a filter that takes no argument offers nothing, which is the answer to having typed a `:` after one.
+
+### inlay hints
+
+a `{% for book in shelf %}` shows the element type it binds, which is what says what `{{ book.… }}` will offer. an `{% include %}` and an `{% extends %}` show the file the name resolves to, which matters because two apps can ship the same template name and only one of them is loaded.
+
+**diagnostics.** a template reports twelve rules — an unclosed block, an unknown tag or filter, a tag used without its `{% load %}`, a missing template or static file, an unknown route or the wrong arguments to one, a block no ancestor declares, and a member django cannot call. each is silent unless the index behind it is authoritative, so a project whose settings cannot be read reports nothing rather than guessing. silence one with `{# ty: ignore #}` or `{# ty: ignore[rule-name] #}`, or configure it under `[tool.ty.rules]` like any other.
+
+an unknown *variable* is still not reported: a context can come from places a scan cannot see, so absence is not evidence.
+
+### the project's django structure
+
+a workspace symbol search answers with the django project as well as with the python in it. searching for a name offers the models, the admin classes, the views a route reaches, the route names, the templates by the name their loader uses, the `{% partialdef %}`s, and the tags and filters the project and its installed apps register — each labelled with what django calls it, beside whatever python contributed under the same name.
+
+a `{% block %}` is deliberately not among them. a block name is chosen against the one template it overrides rather than to be unique in a project, so a search for `content` would answer with one entry per template that declares one. a `{% partialdef %}` is the opposite: it exists to be rendered from elsewhere by name.
 
 ## the same names, written in python
 
@@ -132,9 +150,11 @@ two views rendering the same template both contribute; a name they agree on appe
 
 ## how a template is recognised
 
-the editor usually says so: `django`, `django-html`, `django-txt`, `htmldjango` and `jinja-html` are all taken as django templates.
+the editor usually says so: `django`, `django-html`, `django-txt` and `htmldjango` are all taken as django templates.
 
-when the editor just calls the file `html` — which is what plain vs code does — the path decides: a file with a template-ish extension (`.html`, `.htm`, `.txt`, `.xml`, `.django`, `.dj`, `.jinja`) somewhere under a directory named `templates` is a django template. ordinary html elsewhere in the project is left alone.
+when the editor just calls the file `html` — which is what plain vs code does — the path decides: a file with a template-ish extension (`.html`, `.htm`, `.txt`, `.xml`, `.django`, `.dj`) somewhere under a directory named `templates` is a django template. ordinary html elsewhere in the project is left alone.
+
+jinja is not django, and nothing here is claimed for it. a document the editor calls `jinja`, `jinja-html` or `jinja2` gets no template services at all, and neither does a `.jinja` file — everything below answers as django, so a correct `{% set %}`, `{% macro %}` or `|default("x")` would be reported as an error.
 
 template directories, static directories and tag libraries are found by their conventional names, which is what django's own app-directories loaders use:
 
@@ -162,7 +182,15 @@ only the apps `INSTALLED_APPS` names are looked at — site-packages at large is
 
 a library in `TEMPLATES[*]["OPTIONS"]["builtins"]` is available in every template without a `{% load %}`, so none is suggested for it and none is written.
 
-a project whose settings cannot be read still has its own `templatetags` modules and django's builtin tables, and behaves exactly as it did before.
+### django's own tags and filters
+
+django's implicit builtins — `django.template.defaulttags`, `django.template.defaultfilters` and `django.template.loader_tags`, the modules every engine starts with loaded — are scanned the same way. so `{% for %}`, `{% extends %}` and `|upper` are read off the installed django rather than assumed.
+
+that is what decides which of django's names exist and which library each comes from. a tag this django registers is offered whether or not it is a name we already knew, and a tag we knew that this django does not register is not offered as django's — a `{% partialdef %}` is a builtin in django 6.0 and needed `{% load partials %}` before it, and it is the installed django that says which.
+
+there is a hardcoded table of django's tags and filters behind that, and it supplies what a scan cannot see: which tag closes which block, which tags may appear in between, and the documentation shown in completion and hover.
+
+a project whose settings cannot be read, or whose django cannot be resolved at all, has its own `templatetags` modules and that table, and behaves exactly as it did before.
 
 ## limitations
 

From 465d78044103151d5094ff9cd3979a71ef75e1e0 Mon Sep 17 00:00:00 2001
From: KotlinIsland <65446343+kotlinisland@users.noreply.github.com>
Date: Sat, 8 Aug 2026 21:38:32 +1000
Subject: [PATCH 07/16] a route's parameters must be ones its view can take,
 and by check says so
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

the check found seven real bugs in the probe project itself, every one confirmed
by django raising `TypeError`, with `manage.py check` clean throughout. django does
not check this

reporting on a python file made the editor and `by check` disagree, which is what
got an earlier rule reverted. a `ProjectChecker` trait in `ty_project` that
`ty_ide` registers into fixes it for all fourteen rules at once and keeps
`Project::check` the single place that knows how to check a project — and folding
the rules in beside the type checker's own is what finally made a `ty: ignore` on
one count as used
---
 Cargo.lock                                    |    1 +
 crates/ty/Cargo.toml                          |    1 +
 crates/ty/docs/rules.md                       |  105 +-
 crates/ty/src/lib.rs                          |   49 +-
 crates/ty/tests/cli/django.rs                 |  367 +++++
 crates/ty/tests/cli/main.rs                   |    1 +
 crates/ty_ide/src/django_template.rs          |  160 +-
 crates/ty_ide/src/django_template/project.rs  |  173 ++-
 crates/ty_ide/src/django_template/routes.rs   | 1303 +++++++++++++++++
 crates/ty_ide/src/django_template/symbols.rs  |    2 +-
 crates/ty_ide/src/lib.rs                      |   13 +-
 crates/ty_project/src/db.rs                   |   26 +-
 crates/ty_project/src/lib.rs                  |   78 +-
 crates/ty_project/src/walk.rs                 |   12 +
 .../ty_python_semantic/src/django_template.rs |   87 +-
 crates/ty_python_semantic/src/lib.rs          |   28 +-
 crates/ty_python_semantic/src/types.rs        |   49 +-
 .../src/types/ide_support.rs                  |  106 +-
 .../ty_server/src/server/api/diagnostics.rs   |    5 +
 crates/ty_server/src/session.rs               |    7 +-
 .../frameworks/django-templates.md            |   29 +
 ty.schema.json                                |   20 +
 22 files changed, 2553 insertions(+), 69 deletions(-)
 create mode 100644 crates/ty/tests/cli/django.rs
 create mode 100644 crates/ty_ide/src/django_template/routes.rs

diff --git a/Cargo.lock b/Cargo.lock
index 328270f398..ba2e34f4da 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -4702,6 +4702,7 @@ dependencies = [
  "tracing-flame",
  "tracing-subscriber",
  "ty_combine",
+ "ty_ide",
  "ty_module_resolver",
  "ty_project",
  "ty_python_core",
diff --git a/crates/ty/Cargo.toml b/crates/ty/Cargo.toml
index 69f540e00f..fa8d48571b 100644
--- a/crates/ty/Cargo.toml
+++ b/crates/ty/Cargo.toml
@@ -29,6 +29,7 @@ by_transforms = { workspace = true }
 ruff_ranged_value = { workspace = true }
 ty_combine = { workspace = true }
 ty_module_resolver = { workspace = true }
+ty_ide = { workspace = true }
 ty_project = { workspace = true, features = ["zstd", "junit"] }
 ty_python_semantic = { workspace = true, features = ["serde"] }
 ty_server = { workspace = true }
diff --git a/crates/ty/docs/rules.md b/crates/ty/docs/rules.md
index e6e1a3a935..b195b2a79a 100644
--- a/crates/ty/docs/rules.md
+++ b/crates/ty/docs/rules.md
@@ -3426,7 +3426,7 @@ def func() -> int:
 Default level: <a href="../../rules#rule-levels" title="This lint has a default level of 'error'."><code>error</code></a> ·
 Added in <a href="https://github.com/astral-sh/ty/releases/tag/0.0.69">0.0.69</a> ·
 <a href="https://github.com/astral-sh/ty/issues?q=sort%3Aupdated-desc%20is%3Aissue%20is%3Aopen%20%22invalid-route-arguments%22" target="_blank">Related issues</a> ·
-<a href="https://github.com/astral-sh/ruff/blob/main/crates%2Fty_python_semantic%2Fsrc%2Fdjango_template.rs#L235" target="_blank">View source</a>
+<a href="https://github.com/astral-sh/ruff/blob/main/crates%2Fty_python_semantic%2Fsrc%2Fdjango_template.rs#L241" target="_blank">View source</a>
 </small>
 
 
@@ -3453,6 +3453,87 @@ routes share is reported only when none of them accepts the arguments.
 {% url 'detail' pk=1 %}     {# ok #}
 ```
 
+## `invalid-route-handler`
+
+<small>
+Default level: <a href="../../rules#rule-levels" title="This lint has a default level of 'error'."><code>error</code></a> ·
+Added in <a href="https://github.com/astral-sh/ty/releases/tag/0.0.69">0.0.69</a> ·
+<a href="https://github.com/astral-sh/ty/issues?q=sort%3Aupdated-desc%20is%3Aissue%20is%3Aopen%20%22invalid-route-handler%22" target="_blank">Related issues</a> ·
+<a href="https://github.com/astral-sh/ruff/blob/main/crates%2Fty_python_semantic%2Fsrc%2Fdjango_template.rs#L323" target="_blank">View source</a>
+</small>
+
+
+**What it does**
+
+Checks that the view a route names can take the arguments the route's
+pattern gives it.
+
+**Why is this bad?**
+
+A route pattern names its arguments, and django hands each of them to the
+view as a keyword argument. A view that names them differently, or does
+not take them at all, raises `TypeError` when the url is requested — a
+failure nothing reports until the page 500s.
+
+Only a project whose url tree could be walked in full is checked, since a
+route's arguments include the ones the patterns it is mounted behind
+contribute. A view taking `*args` or `**kwargs` accepts anything and is
+never reported, nor is one reached through a decorator the type checker
+cannot see through. A class-based view is checked through the handler
+methods it declares itself: what it inherits from django takes `**kwargs`.
+
+**Examples**
+
+```python
+path("books/<int:pk>/", views.detail, name="detail")
+```
+
+```python
+def detail(request, id): ...     # error: the route names `pk`
+def detail(request): ...         # error: `pk` has nowhere to go
+def detail(request, pk): ...     # ok
+```
+
+## `invalid-route-parameter-type`
+
+<small>
+Default level: <a href="../../rules#rule-levels" title="This lint has a default level of 'warn'."><code>warn</code></a> ·
+Added in <a href="https://github.com/astral-sh/ty/releases/tag/0.0.69">0.0.69</a> ·
+<a href="https://github.com/astral-sh/ty/issues?q=sort%3Aupdated-desc%20is%3Aissue%20is%3Aopen%20%22invalid-route-parameter-type%22" target="_blank">Related issues</a> ·
+<a href="https://github.com/astral-sh/ruff/blob/main/crates%2Fty_python_semantic%2Fsrc%2Fdjango_template.rs#L358" target="_blank">View source</a>
+</small>
+
+
+**What it does**
+
+Checks the type a view declares for a route argument against the type the
+route's converter produces.
+
+**Why is this bad?**
+
+A path converter parses the url before django calls the view:
+`<int:pk>` hands the view an `int` and `<uuid:key>` a `uuid.UUID`. A view
+declaring something else is annotated with a type its argument never has,
+so everything written against the annotation is written against a value
+that is not there.
+
+Unlike [`invalid-route-handler`](#invalid-route-handler) this does not stop the request: django
+calls the view and the wrong value arrives silently.
+An unannotated parameter declares nothing and is never reported,
+and neither is one matched by a regular expression, which goes through no
+converter at all.
+
+**Examples**
+
+```python
+path("books/<int:pk>/", views.detail, name="detail")
+```
+
+```python
+def detail(request, pk: str): ...    # warning: the converter gives an `int`
+def detail(request, pk: int): ...    # ok
+```
+
 ## `invalid-super-argument`
 
 <small>
@@ -6049,7 +6130,7 @@ class F(NamedTuple):
 Default level: <a href="../../rules#rule-levels" title="This lint has a default level of 'warn'."><code>warn</code></a> ·
 Added in <a href="https://github.com/astral-sh/ty/releases/tag/0.0.69">0.0.69</a> ·
 <a href="https://github.com/astral-sh/ty/issues?q=sort%3Aupdated-desc%20is%3Aissue%20is%3Aopen%20%22template-member-needs-arguments%22" target="_blank">Related issues</a> ·
-<a href="https://github.com/astral-sh/ruff/blob/main/crates%2Fty_python_semantic%2Fsrc%2Fdjango_template.rs#L289" target="_blank">View source</a>
+<a href="https://github.com/astral-sh/ruff/blob/main/crates%2Fty_python_semantic%2Fsrc%2Fdjango_template.rs#L295" target="_blank">View source</a>
 </small>
 
 
@@ -6393,7 +6474,7 @@ class C(Generic[T]):
 Default level: <a href="../../rules#rule-levels" title="This lint has a default level of 'error'."><code>error</code></a> ·
 Added in <a href="https://github.com/astral-sh/ty/releases/tag/0.0.69">0.0.69</a> ·
 <a href="https://github.com/astral-sh/ty/issues?q=sort%3Aupdated-desc%20is%3Aissue%20is%3Aopen%20%22unclosed-template-block%22" target="_blank">Related issues</a> ·
-<a href="https://github.com/astral-sh/ruff/blob/main/crates%2Fty_python_semantic%2Fsrc%2Fdjango_template.rs#L28" target="_blank">View source</a>
+<a href="https://github.com/astral-sh/ruff/blob/main/crates%2Fty_python_semantic%2Fsrc%2Fdjango_template.rs#L34" target="_blank">View source</a>
 </small>
 
 
@@ -6577,7 +6658,7 @@ def test_thing(no_such_fixture) -> None:  # requests an unknown fixture
 Default level: <a href="../../rules#rule-levels" title="This lint has a default level of 'warn'."><code>warn</code></a> ·
 Added in <a href="https://github.com/astral-sh/ty/releases/tag/0.0.69">0.0.69</a> ·
 <a href="https://github.com/astral-sh/ty/issues?q=sort%3Aupdated-desc%20is%3Aissue%20is%3Aopen%20%22unknown-template-block%22" target="_blank">Related issues</a> ·
-<a href="https://github.com/astral-sh/ruff/blob/main/crates%2Fty_python_semantic%2Fsrc%2Fdjango_template.rs#L262" target="_blank">View source</a>
+<a href="https://github.com/astral-sh/ruff/blob/main/crates%2Fty_python_semantic%2Fsrc%2Fdjango_template.rs#L268" target="_blank">View source</a>
 </small>
 
 
@@ -6610,7 +6691,7 @@ part of its enclosing block and needs no declaration above it.
 Default level: <a href="../../rules#rule-levels" title="This lint has a default level of 'error'."><code>error</code></a> ·
 Added in <a href="https://github.com/astral-sh/ty/releases/tag/0.0.69">0.0.69</a> ·
 <a href="https://github.com/astral-sh/ty/issues?q=sort%3Aupdated-desc%20is%3Aissue%20is%3Aopen%20%22unknown-template-filter%22" target="_blank">Related issues</a> ·
-<a href="https://github.com/astral-sh/ruff/blob/main/crates%2Fty_python_semantic%2Fsrc%2Fdjango_template.rs#L119" target="_blank">View source</a>
+<a href="https://github.com/astral-sh/ruff/blob/main/crates%2Fty_python_semantic%2Fsrc%2Fdjango_template.rs#L125" target="_blank">View source</a>
 </small>
 
 
@@ -6638,7 +6719,7 @@ A filter whose library the template has simply not loaded is reported as
 Default level: <a href="../../rules#rule-levels" title="This lint has a default level of 'error'."><code>error</code></a> ·
 Added in <a href="https://github.com/astral-sh/ty/releases/tag/0.0.69">0.0.69</a> ·
 <a href="https://github.com/astral-sh/ty/issues?q=sort%3Aupdated-desc%20is%3Aissue%20is%3Aopen%20%22unknown-template-library%22" target="_blank">Related issues</a> ·
-<a href="https://github.com/astral-sh/ruff/blob/main/crates%2Fty_python_semantic%2Fsrc%2Fdjango_template.rs#L73" target="_blank">View source</a>
+<a href="https://github.com/astral-sh/ruff/blob/main/crates%2Fty_python_semantic%2Fsrc%2Fdjango_template.rs#L79" target="_blank">View source</a>
 </small>
 
 
@@ -6668,7 +6749,7 @@ reached is not a library that is missing.
 Default level: <a href="../../rules#rule-levels" title="This lint has a default level of 'error'."><code>error</code></a> ·
 Added in <a href="https://github.com/astral-sh/ty/releases/tag/0.0.69">0.0.69</a> ·
 <a href="https://github.com/astral-sh/ty/issues?q=sort%3Aupdated-desc%20is%3Aissue%20is%3Aopen%20%22unknown-template-tag%22" target="_blank">Related issues</a> ·
-<a href="https://github.com/astral-sh/ruff/blob/main/crates%2Fty_python_semantic%2Fsrc%2Fdjango_template.rs#L97" target="_blank">View source</a>
+<a href="https://github.com/astral-sh/ruff/blob/main/crates%2Fty_python_semantic%2Fsrc%2Fdjango_template.rs#L103" target="_blank">View source</a>
 </small>
 
 
@@ -6696,7 +6777,7 @@ A tag whose library the template has simply not loaded is reported as
 Default level: <a href="../../rules#rule-levels" title="This lint has a default level of 'error'."><code>error</code></a> ·
 Added in <a href="https://github.com/astral-sh/ty/releases/tag/0.0.69">0.0.69</a> ·
 <a href="https://github.com/astral-sh/ty/issues?q=sort%3Aupdated-desc%20is%3Aissue%20is%3Aopen%20%22unloaded-template-library%22" target="_blank">Related issues</a> ·
-<a href="https://github.com/astral-sh/ruff/blob/main/crates%2Fty_python_semantic%2Fsrc%2Fdjango_template.rs#L141" target="_blank">View source</a>
+<a href="https://github.com/astral-sh/ruff/blob/main/crates%2Fty_python_semantic%2Fsrc%2Fdjango_template.rs#L147" target="_blank">View source</a>
 </small>
 
 
@@ -6724,7 +6805,7 @@ every template already and is never reported.
 Default level: <a href="../../rules#rule-levels" title="This lint has a default level of 'error'."><code>error</code></a> ·
 Added in <a href="https://github.com/astral-sh/ty/releases/tag/0.0.69">0.0.69</a> ·
 <a href="https://github.com/astral-sh/ty/issues?q=sort%3Aupdated-desc%20is%3Aissue%20is%3Aopen%20%22unmatched-template-close%22" target="_blank">Related issues</a> ·
-<a href="https://github.com/astral-sh/ruff/blob/main/crates%2Fty_python_semantic%2Fsrc%2Fdjango_template.rs#L51" target="_blank">View source</a>
+<a href="https://github.com/astral-sh/ruff/blob/main/crates%2Fty_python_semantic%2Fsrc%2Fdjango_template.rs#L57" target="_blank">View source</a>
 </small>
 
 
@@ -6947,7 +7028,7 @@ print(x)  # error
 Default level: <a href="../../rules#rule-levels" title="This lint has a default level of 'error'."><code>error</code></a> ·
 Added in <a href="https://github.com/astral-sh/ty/releases/tag/0.0.69">0.0.69</a> ·
 <a href="https://github.com/astral-sh/ty/issues?q=sort%3Aupdated-desc%20is%3Aissue%20is%3Aopen%20%22unresolved-route%22" target="_blank">Related issues</a> ·
-<a href="https://github.com/astral-sh/ruff/blob/main/crates%2Fty_python_semantic%2Fsrc%2Fdjango_template.rs#L211" target="_blank">View source</a>
+<a href="https://github.com/astral-sh/ruff/blob/main/crates%2Fty_python_semantic%2Fsrc%2Fdjango_template.rs#L217" target="_blank">View source</a>
 </small>
 
 
@@ -6977,7 +7058,7 @@ walked in full, reports nothing.
 Default level: <a href="../../rules#rule-levels" title="This lint has a default level of 'warn'."><code>warn</code></a> ·
 Added in <a href="https://github.com/astral-sh/ty/releases/tag/0.0.69">0.0.69</a> ·
 <a href="https://github.com/astral-sh/ty/issues?q=sort%3Aupdated-desc%20is%3Aissue%20is%3Aopen%20%22unresolved-static-file%22" target="_blank">Related issues</a> ·
-<a href="https://github.com/astral-sh/ruff/blob/main/crates%2Fty_python_semantic%2Fsrc%2Fdjango_template.rs#L187" target="_blank">View source</a>
+<a href="https://github.com/astral-sh/ruff/blob/main/crates%2Fty_python_semantic%2Fsrc%2Fdjango_template.rs#L193" target="_blank">View source</a>
 </small>
 
 
@@ -7007,7 +7088,7 @@ not something the source tree can answer.
 Default level: <a href="../../rules#rule-levels" title="This lint has a default level of 'error'."><code>error</code></a> ·
 Added in <a href="https://github.com/astral-sh/ty/releases/tag/0.0.69">0.0.69</a> ·
 <a href="https://github.com/astral-sh/ty/issues?q=sort%3Aupdated-desc%20is%3Aissue%20is%3Aopen%20%22unresolved-template%22" target="_blank">Related issues</a> ·
-<a href="https://github.com/astral-sh/ruff/blob/main/crates%2Fty_python_semantic%2Fsrc%2Fdjango_template.rs#L163" target="_blank">View source</a>
+<a href="https://github.com/astral-sh/ruff/blob/main/crates%2Fty_python_semantic%2Fsrc%2Fdjango_template.rs#L169" target="_blank">View source</a>
 </small>
 
 
diff --git a/crates/ty/src/lib.rs b/crates/ty/src/lib.rs
index dded0b06fc..a1c372b659 100644
--- a/crates/ty/src/lib.rs
+++ b/crates/ty/src/lib.rs
@@ -8,7 +8,7 @@ mod version;
 
 use std::io::{BufWriter, Write};
 use std::process::{ExitCode, Termination};
-use std::sync::Mutex;
+use std::sync::{Arc, Mutex};
 
 use anyhow::Result;
 use anyhow::{Context, anyhow};
@@ -18,7 +18,7 @@ use crossbeam::channel as crossbeam_channel;
 use rayon::ThreadPoolBuilder;
 use ruff_db::cancellation::{Canceled, CancellationToken, CancellationTokenSource};
 use ruff_db::diagnostic::{
-    Diagnostic, DiagnosticId, DisplayDiagnosticConfig, DisplayDiagnostics, Severity,
+    Diagnostic, DiagnosticId, DisplayDiagnosticConfig, DisplayDiagnostics, Severity, UnifiedFile,
 };
 use ruff_db::files::File;
 use ruff_db::system::{OsSystem, SystemPath, SystemPathBuf};
@@ -290,6 +290,13 @@ fn run_check(args: CheckCommand) -> anyhow::Result<ExitStatus> {
     project_metadata.apply_override_options(args.into_options());
 
     let mut db = ProjectDatabase::fallible(project_metadata, system)?;
+
+    // the project's django, which the type checker does not read: its templates are
+    // checked alongside the python files, and what its routes get wrong is folded
+    // into the python files' own diagnostics. a project without django registers a
+    // checker that answers with nothing, and pays nothing
+    db.set_checker(Arc::new(ty_ide::DjangoChecker));
+
     let project = db.project();
 
     project.set_verbose(&mut db, verbosity >= VerbosityLevel::Verbose);
@@ -524,6 +531,11 @@ impl MainLoop {
                             }
                         }
                         MainLoopMode::Fix(mode) => {
+                            // both of these rewrite a file through its python tokens, so a
+                            // diagnostic on a file that is not python is reported unchanged
+                            // rather than fixed
+                            let (result, other_language) = split_other_language(db, result);
+
                             let result = match mode {
                                 FixMode::AddIgnore => {
                                     suppress_all_diagnostics(db, result, &self.cancellation_token)
@@ -536,7 +548,12 @@ impl MainLoop {
                                 ),
                             };
 
-                            if let Ok(result) = result {
+                            if let Ok(mut result) = result {
+                                result.diagnostics.extend(other_language);
+                                result.diagnostics.sort_by(|left, right| {
+                                    left.rendering_sort_key(db)
+                                        .cmp(&right.rendering_sort_key(db))
+                                });
                                 let fixed_diagnostics = match mode {
                                     FixMode::AddIgnore => None,
                                     FixMode::ApplyFixes => Some(result.count),
@@ -692,6 +709,32 @@ enum FixMode {
     ApplyFixes,
 }
 
+/// Split `diagnostics` into the python ones and the ones a registered
+/// [`ty_project::ProjectChecker`] owns the file of.
+///
+/// Everything that rewrites a file — applying a fix, adding an ignore comment —
+/// works through the file's python tokens, and the second group has none.
+fn split_other_language(
+    db: &ProjectDatabase,
+    diagnostics: Vec<Diagnostic>,
+) -> (Vec<Diagnostic>, Vec<Diagnostic>) {
+    let Some(checker) = db.project_checker() else {
+        return (diagnostics, Vec::new());
+    };
+
+    diagnostics.into_iter().partition(|diagnostic| {
+        let owned = diagnostic
+            .primary_span_ref()
+            .and_then(|span| match span.file() {
+                UnifiedFile::Ty(file) => file.path(db).as_system_path(),
+                UnifiedFile::Ruff(_) => None,
+            })
+            .is_some_and(|path| checker.owns(db, path));
+
+        !owned
+    })
+}
+
 fn exit_status_from_diagnostics(
     diagnostics: &[Diagnostic],
     terminal_settings: &TerminalSettings,
diff --git a/crates/ty/tests/cli/django.rs b/crates/ty/tests/cli/django.rs
new file mode 100644
index 0000000000..8a41b9b883
--- /dev/null
+++ b/crates/ty/tests/cli/django.rs
@@ -0,0 +1,367 @@
+//! `by check` over a django project.
+//!
+//! A template is not python and is not in the project's file set, so these are
+//! also the tests that say `by check` reaches a file the type checker never sees —
+//! and that it still never reads one as python.
+
+use crate::CliTest;
+use insta_cmd::assert_cmd_snapshot;
+
+/// A django project whose settings, templates and url tree can all be read.
+///
+/// `django` is written *outside* the project root and reached through an extra
+/// search path, which is what makes it an installed package rather than source of
+/// the project's own — the same difference site-packages makes.
+fn django_project(files: &[(&str, &str)]) -> anyhow::Result<CliTest> {
+    let mut all: Vec<(&str, &str)> = vec![
+        (
+            "ty.toml",
+            r#"
+            [environment]
+            extra-paths = ["../libs"]
+            "#,
+        ),
+        (
+            "manage.py",
+            r#"
+            import os
+
+            os.environ.setdefault("DJANGO_SETTINGS_MODULE", "project.settings")
+            "#,
+        ),
+        ("project/__init__.py", ""),
+        (
+            "project/settings.py",
+            r#"
+            INSTALLED_APPS = ["blog"]
+
+            TEMPLATES = [{"DIRS": [], "APP_DIRS": True, "OPTIONS": {}}]
+
+            ROOT_URLCONF = "project.urls"
+            "#,
+        ),
+        (
+            "project/urls.py",
+            r#"
+            from django.urls import include, path
+
+            urlpatterns = [path("blog/", include("blog.urls"))]
+            "#,
+        ),
+        ("blog/__init__.py", ""),
+        (
+            "blog/views.py",
+            "
+            def index(request): ...
+
+
+            def detail(request, pk: int): ...
+            ",
+        ),
+        (
+            "blog/urls.py",
+            r#"
+            from django.urls import path
+
+            from blog import views
+
+            app_name = "blog"
+
+            urlpatterns = [
+                path("", views.index, name="index"),
+                path("<int:pk>/", views.detail, name="detail"),
+            ]
+            "#,
+        ),
+        (
+            "blog/templates/blog/base.html",
+            "{% block content %}{% endblock %}",
+        ),
+    ];
+    all.extend_from_slice(files);
+
+    let case = CliTest::with_files(all)?;
+
+    write_installed(
+        &case,
+        &[
+            ("django/__init__.py", ""),
+            (
+                "django/urls/__init__.py",
+                "def path(route, view, kwargs=None, name=None): ...\n\
+                 def include(arg, namespace=None): ...\n",
+            ),
+        ],
+    )?;
+
+    Ok(case)
+}
+
+/// Write packages to the `libs` directory beside the project root, which
+/// [`django_project`] puts on the search path.
+fn write_installed(case: &CliTest, files: &[(&str, &str)]) -> anyhow::Result<()> {
+    let libs = case
+        .root()
+        .parent()
+        .expect("the project directory always has a parent")
+        .join("libs");
+
+    for (path, content) in files {
+        let path = libs.join(path);
+        if let Some(parent) = path.parent() {
+            std::fs::create_dir_all(parent)?;
+        }
+        std::fs::write(path, content)?;
+    }
+
+    Ok(())
+}
+
+#[test]
+fn a_template_is_checked() -> anyhow::Result<()> {
+    let case = django_project(&[(
+        "blog/templates/blog/post.html",
+        "{% if book %}\n<p>{{ book.title|uppercase }}</p>\n",
+    )])?;
+
+    assert_cmd_snapshot!(case.command().arg("--output-format=concise"), @r"
+    success: false
+    exit_code: 1
+    ----- stdout -----
+    blog/templates/blog/post.html:1:1: error[unclosed-template-block] unclosed `if`
+    blog/templates/blog/post.html:2:18: error[unknown-template-filter] no template filter named `uppercase`
+    Found 2 diagnostics
+
+    ----- stderr -----
+    ");
+
+    Ok(())
+}
+
+#[test]
+fn a_template_is_never_read_as_python() -> anyhow::Result<()> {
+    // every line of this is a python syntax error, and the only thing reported is
+    // the one thing wrong with it as a template
+    let case = django_project(&[(
+        "blog/templates/blog/post.html",
+        "<ul>\n{% for book in books %}\n  <li>{{ book.title }}</li>\n",
+    )])?;
+
+    assert_cmd_snapshot!(case.command().arg("--output-format=concise"), @r"
+    success: false
+    exit_code: 1
+    ----- stdout -----
+    blog/templates/blog/post.html:2:1: error[unclosed-template-block] unclosed `for`
+    Found 1 diagnostic
+
+    ----- stderr -----
+    ");
+
+    Ok(())
+}
+
+#[test]
+fn a_template_named_on_the_command_line_is_still_not_read_as_python() -> anyhow::Result<()> {
+    // a path passed explicitly is otherwise taken to be something ty can analyze,
+    // whatever its extension
+    let case = django_project(&[("blog/templates/blog/post.html", "{% for book in books %}\n")])?;
+
+    assert_cmd_snapshot!(
+        case.command()
+            .arg("--output-format=concise")
+            .arg("blog/templates/blog/post.html"),
+        @r"
+    success: false
+    exit_code: 1
+    ----- stdout -----
+    blog/templates/blog/post.html:1:1: error[unclosed-template-block] unclosed `for`
+    Found 1 diagnostic
+
+    ----- stderr -----
+    WARN No python files found under the given path(s)
+    "
+    );
+
+    Ok(())
+}
+
+#[test]
+fn a_suppression_comment_in_a_template_silences_it() -> anyhow::Result<()> {
+    let case = django_project(&[(
+        "blog/templates/blog/post.html",
+        "{% if book %}{# ty: ignore[unclosed-template-block] #}\n\
+         <p>{{ book.title|uppercase }}</p>{# ty: ignore[unknown-template-filter] #}\n",
+    )])?;
+
+    assert_cmd_snapshot!(case.command(), @"
+    success: true
+    exit_code: 0
+    ----- stdout -----
+    All checks passed!
+
+    ----- stderr -----
+    ");
+
+    Ok(())
+}
+
+#[test]
+fn a_template_rule_is_configured_like_any_other() -> anyhow::Result<()> {
+    let case = django_project(&[
+        (
+            "blog/templates/blog/post.html",
+            "{% if book %}\n<p>{{ book.title|uppercase }}</p>\n",
+        ),
+        (
+            "ty.toml",
+            r#"
+            [environment]
+            extra-paths = ["../libs"]
+
+            [rules]
+            unclosed-template-block = "warn"
+            unknown-template-filter = "ignore"
+            "#,
+        ),
+    ])?;
+
+    assert_cmd_snapshot!(case.command().arg("--output-format=concise"), @r"
+    success: false
+    exit_code: 1
+    ----- stdout -----
+    blog/templates/blog/post.html:1:1: warning[unclosed-template-block] unclosed `if`
+    Found 1 diagnostic
+
+    ----- stderr -----
+    ");
+
+    Ok(())
+}
+
+#[test]
+fn a_route_its_view_cannot_serve_is_reported() -> anyhow::Result<()> {
+    let case = django_project(&[(
+        "blog/urls.py",
+        r#"
+        from django.urls import path
+
+        from blog import views
+
+        app_name = "blog"
+
+        urlpatterns = [
+            path("<int:missing>/", views.index, name="broken"),
+        ]
+        "#,
+    )])?;
+
+    assert_cmd_snapshot!(case.command().arg("--output-format=concise"), @r"
+    success: false
+    exit_code: 1
+    ----- stdout -----
+    blog/urls.py:9:28: error[invalid-route-handler] `index` takes no argument named `missing`
+    Found 1 diagnostic
+
+    ----- stderr -----
+    ");
+
+    Ok(())
+}
+
+#[test]
+fn a_suppression_that_silenced_a_route_is_not_reported_unused() -> anyhow::Result<()> {
+    let case = django_project(&[(
+        "blog/urls.py",
+        r#"
+        from django.urls import path
+
+        from blog import views
+
+        app_name = "blog"
+
+        urlpatterns = [
+            path("<int:missing>/", views.index, name="broken"),  # ty: ignore[invalid-route-handler]
+        ]
+        "#,
+    )])?;
+
+    assert_cmd_snapshot!(case.command(), @"
+    success: true
+    exit_code: 0
+    ----- stdout -----
+    All checks passed!
+
+    ----- stderr -----
+    ");
+
+    Ok(())
+}
+
+#[test]
+fn an_installed_apps_own_templates_are_not_the_projects_to_report() -> anyhow::Result<()> {
+    // django loads these exactly as it loads the project's, and everything that
+    // reads a template reaches them — but they are a dependency's source
+    let case = django_project(&[
+        (
+            "project/settings.py",
+            r#"
+            INSTALLED_APPS = ["django.contrib.admin", "blog"]
+
+            TEMPLATES = [{"DIRS": [], "APP_DIRS": True, "OPTIONS": {}}]
+
+            ROOT_URLCONF = "project.urls"
+            "#,
+        ),
+        // the same fault, in the project. it is what says the installed one was
+        // discovered and left alone rather than never discovered at all
+        ("blog/templates/blog/post.html", "{% if broken %}\n"),
+    ])?;
+
+    write_installed(
+        &case,
+        &[
+            ("django/contrib/__init__.py", ""),
+            ("django/contrib/admin/__init__.py", ""),
+            (
+                "django/contrib/admin/templates/admin/base.html",
+                "{% if broken %}\n",
+            ),
+        ],
+    )?;
+
+    assert_cmd_snapshot!(case.command().arg("--output-format=concise"), @r"
+    success: false
+    exit_code: 1
+    ----- stdout -----
+    blog/templates/blog/post.html:1:1: error[unclosed-template-block] unclosed `if`
+    Found 1 diagnostic
+
+    ----- stderr -----
+    ");
+
+    Ok(())
+}
+
+#[test]
+fn a_project_without_django_reports_nothing_about_its_templates() -> anyhow::Result<()> {
+    // `templates/index.html` in a flask or a jinja project is not a django
+    // template, and nothing here knows what its language even is
+    let case = CliTest::with_files([
+        ("app.py", "x: int = 1"),
+        (
+            "templates/index.html",
+            "{% if book %}\n{{ book|uppercase }}\n",
+        ),
+    ])?;
+
+    assert_cmd_snapshot!(case.command(), @"
+    success: true
+    exit_code: 0
+    ----- stdout -----
+    All checks passed!
+
+    ----- stderr -----
+    ");
+
+    Ok(())
+}
diff --git a/crates/ty/tests/cli/main.rs b/crates/ty/tests/cli/main.rs
index 4d7e1cd364..1327161160 100644
--- a/crates/ty/tests/cli/main.rs
+++ b/crates/ty/tests/cli/main.rs
@@ -1,6 +1,7 @@
 mod analysis_options;
 mod api_lockfile;
 mod config_option;
+mod django;
 mod exit_code;
 mod file_selection;
 mod fixes;
diff --git a/crates/ty_ide/src/django_template.rs b/crates/ty_ide/src/django_template.rs
index 08c32ed792..b46ac4c314 100644
--- a/crates/ty_ide/src/django_template.rs
+++ b/crates/ty_ide/src/django_template.rs
@@ -28,6 +28,7 @@ mod python;
 mod references;
 mod rename;
 mod resolve;
+mod routes;
 mod semantic_tokens;
 mod signature_help;
 mod symbols;
@@ -45,11 +46,12 @@ pub use signature_help::TemplateSignature;
 pub use symbols::{DjangoSymbol, TemplateSymbol};
 
 use ruff_db::diagnostic::Diagnostic;
-use ruff_db::files::File;
+use ruff_db::files::{File, system_path_to_file};
 use ruff_db::source::source_text;
 use ruff_db::system::SystemPath;
 use ruff_text_size::{TextRange, TextSize};
 use ty_project::Db;
+use ty_project::glob::IncludeResult;
 
 use ty_python_semantic::lint::LintId;
 
@@ -203,10 +205,72 @@ fn ancestors<'db>(
 /// the type checker never sees a template — it is not python — so this is the
 /// whole of what a template document can report.
 pub fn django_template_diagnostics(db: &dyn Db, file: File) -> Vec<Diagnostic> {
+    if !project::has_django(db, db.project()) {
+        return Vec::new();
+    }
+
     let source = source_text(db, file);
     diagnostics::diagnostics(db, file, template_index(db, file), source.as_str())
 }
 
+/// everything wrong with the django a python file writes
+///
+/// this is what the type checker's own pass over the file cannot say: whether a
+/// route's view can take the arguments the route gives it is a question about the
+/// project's whole url tree, which is read here rather than there.
+///
+/// the file's suppression comments are deliberately *not* applied: these are
+/// folded into the type checker's own diagnostics, which is where a `ty: ignore`
+/// is honoured and counted used — see [`ty_python_semantic::check_file_with`].
+pub fn django_python_diagnostics(db: &dyn Db, file: File) -> Vec<Diagnostic> {
+    routes::diagnostics(db, file)
+}
+
+/// django's checks, as something [`ty_project::Project::check`] can run
+///
+/// registering this is what makes the command line and an editor report the same
+/// rules in the same places: both reach the two functions above, and both reach
+/// them through the same suppression and configuration.
+#[derive(Debug, Default, Clone, Copy)]
+pub struct DjangoChecker;
+
+impl ty_project::ProjectChecker for DjangoChecker {
+    fn owns(&self, db: &dyn Db, path: &SystemPath) -> bool {
+        is_django_template_path(path) && project::has_django(db, db.project())
+    }
+
+    fn files(&self, db: &dyn Db) -> Vec<File> {
+        let project = db.project();
+        if !project::has_django(db, project) {
+            return Vec::new();
+        }
+
+        project::template_files(db, project)
+            .iter()
+            // an installed app's templates are django's or a dependency's, and a
+            // project is no more answerable for those than for the python beside them
+            .filter(|discovered| discovered.own)
+            // the same include, exclude and `ty check <paths>` filtering the python
+            // files of the project go through
+            .filter(|discovered| {
+                matches!(
+                    project.is_file_included(db, &discovered.path),
+                    IncludeResult::Included { .. }
+                )
+            })
+            .filter_map(|discovered| system_path_to_file(db, &discovered.path).ok())
+            .collect()
+    }
+
+    fn check_file(&self, db: &dyn Db, file: File) -> Vec<Diagnostic> {
+        django_template_diagnostics(db, file)
+    }
+
+    fn check_python_file(&self, db: &dyn Db, file: File) -> Vec<Diagnostic> {
+        django_python_diagnostics(db, file)
+    }
+}
+
 /// the quick fixes offered for a template diagnostic at `range`
 pub(crate) fn django_template_code_actions(
     db: &dyn Db,
@@ -352,11 +416,11 @@ pub(crate) mod tests {
 
     use super::{
         DjangoLensAction, PreparedTemplateRename, TemplateRenameOutcome, TemplateSymbol,
-        django_prepare_rename, django_python_code_lenses, django_references, django_rename,
-        django_template_code_lenses, django_template_completions, django_template_diagnostics,
-        django_template_document_symbols, django_template_folding_ranges,
-        django_template_goto_definition, django_template_hover, django_template_inlay_hints,
-        django_template_signature_help, is_django_template_path,
+        django_prepare_rename, django_python_code_lenses, django_python_diagnostics,
+        django_references, django_rename, django_template_code_lenses, django_template_completions,
+        django_template_diagnostics, django_template_document_symbols,
+        django_template_folding_ranges, django_template_goto_definition, django_template_hover,
+        django_template_inlay_hints, django_template_signature_help, is_django_template_path,
     };
 
     /// a mock django whose implicit builtins are there to be read
@@ -459,6 +523,9 @@ pub(crate) mod tests {
         pub(crate) db: TestDb,
         pub(crate) file: File,
         pub(crate) offset: TextSize,
+        /// the project root the sources were written under, for a test that
+        /// names a second file of its own
+        root: SystemPathBuf,
     }
 
     impl TemplateTest {
@@ -550,7 +617,86 @@ pub(crate) mod tests {
 
             let (file, offset) = cursor
                 .unwrap_or_else(|| (last.expect("a source to be written"), TextSize::default()));
-            Self { db, file, offset }
+            Self {
+                db,
+                file,
+                offset,
+                root: root.to_path_buf(),
+            }
+        }
+
+        /// rewrite one of the project's files
+        ///
+        /// this is for a test that varies a source the fixture already wrote —
+        /// the url configuration a route is mounted from, most often.
+        pub(crate) fn rewrite(&mut self, path: &str, contents: &str) {
+            self.db
+                .write_file(self.root.join(path), dedent(contents).as_ref())
+                .unwrap();
+        }
+
+        /// every django diagnostic of the python file at `path`, rendered as
+        /// `rule severity: message [text]`
+        ///
+        /// what the type checker itself reports about the file is deliberately
+        /// left out: this is the django join, and mixing the two would make every
+        /// test below depend on how a mock django happens to be annotated.
+        pub(crate) fn python_diagnostics(&self, path: &str) -> Vec<String> {
+            let file = system_path_to_file(&self.db, self.root.join(path))
+                .expect("the file to have been written");
+            let source = ruff_db::source::source_text(&self.db, file);
+
+            django_python_diagnostics(&self.db, file)
+                .into_iter()
+                .map(|diagnostic| {
+                    let range = diagnostic
+                        .primary_span()
+                        .and_then(|span| span.range())
+                        .unwrap_or_default();
+
+                    format!(
+                        "{} {:?}: {} [{}]",
+                        diagnostic.id(),
+                        diagnostic.severity(),
+                        diagnostic.primary_message(),
+                        &source[range]
+                    )
+                })
+                .collect()
+        }
+
+        /// the same, as the project check reports it
+        ///
+        /// [`python_diagnostics`](Self::python_diagnostics) is the raw scan, which
+        /// answers before any `ty: ignore` is read. this is that scan folded into
+        /// the type checker's own pass, which is where a suppression comment is
+        /// honoured and counted used — so it is also what says whether
+        /// `unused-ignore-comment` then fires on the comment that did the silencing.
+        pub(crate) fn checked_python_diagnostics(&self, path: &str) -> Vec<String> {
+            const REPORTED: &[&str] = &[
+                "invalid-route-handler",
+                "invalid-route-parameter-type",
+                "unused-ignore-comment",
+            ];
+
+            let file = system_path_to_file(&self.db, self.root.join(path))
+                .expect("the file to have been written");
+            let external = django_python_diagnostics(&self.db, file);
+
+            ty_python_semantic::check_file_with(&self.db, file, external)
+                .expect("the file to be readable")
+                .iter()
+                // the mock django the fixtures install is annotated no further than
+                // each test needs, so what the type checker itself says about a view
+                // is no business of a test about the django join
+                .filter(|diagnostic| {
+                    diagnostic
+                        .id()
+                        .as_lint()
+                        .is_some_and(|name| REPORTED.contains(&name.as_str()))
+                })
+                .map(|diagnostic| format!("{}: {}", diagnostic.id(), diagnostic.primary_message()))
+                .collect()
         }
 
         /// every diagnostic of the file under test, rendered as
diff --git a/crates/ty_ide/src/django_template/project.rs b/crates/ty_ide/src/django_template/project.rs
index ccefafc01e..68e9443669 100644
--- a/crates/ty_ide/src/django_template/project.rs
+++ b/crates/ty_ide/src/django_template/project.rs
@@ -24,12 +24,17 @@ use ruff_python_ast::visitor::{Visitor, walk_expr, walk_stmt};
 use ruff_python_ast::{self as ast, AnyNodeRef, Expr, Stmt};
 use ruff_text_size::{Ranged, TextRange, TextSize};
 use rustc_hash::{FxHashMap, FxHashSet};
-use ty_module_resolver::{Module, ModuleName, file_to_module, resolve_module, resolve_real_module};
+use ty_module_resolver::{
+    Module, ModuleName, file_to_module, resolve_module, resolve_module_confident,
+    resolve_real_module,
+};
 use ty_project::{Db, Project};
 use ty_python_semantic::SemanticModel;
 use ty_python_semantic::types::ide_support::{
     ImportAliasResolution, ResolvedDefinition, definitions_for_attribute, definitions_for_name,
+    instance_of_class,
 };
+use ty_python_semantic::types::{KnownClass, Type};
 
 /// the directory name django's app-directories template loader looks in
 const TEMPLATE_DIRECTORY: &str = "templates";
@@ -344,7 +349,28 @@ pub(crate) struct UrlName {
     /// writing them out, so what one of them takes cannot be read off `route`.
     pub(crate) exact: bool,
     /// the view the route hands the request to, where it names one this can read
-    pub(crate) view: Option<Target>,
+    pub(crate) view: Option<RouteView>,
+    /// whether the route hands the view arguments its pattern does not name
+    ///
+    /// `path()` takes a dict of extra keyword arguments django passes on top of
+    /// whatever the pattern captured, so a view with a parameter the pattern says
+    /// nothing about may still be called with one.
+    pub(crate) extra_arguments: bool,
+}
+
+/// the view a route hands the request to
+#[derive(Debug, Clone, PartialEq, Eq, get_size2::GetSize)]
+pub(crate) struct RouteView {
+    /// where the view is declared
+    pub(crate) target: Target,
+    /// where the route names it, for a diagnostic about the pairing to point at
+    pub(crate) range: TextRange,
+    /// whether the route reaches it through `as_view()`
+    ///
+    /// django calls what `as_view()` returns rather than the class itself, so a
+    /// class reached that way serves the request through its handler methods
+    /// rather than through anything the class declares directly.
+    pub(crate) class_based: bool,
 }
 
 /// what a python definition a django construct names is
@@ -371,10 +397,41 @@ impl UrlName {
     pub(crate) fn parameters(&self) -> Option<Vec<Parameter>> {
         self.exact
             .then_some(self.route.as_deref()?)
-            .and_then(parameters_of)
+            .and_then(|route| parameters_of(route, DJANGO_SYNTAX))
     }
 }
 
+/// how a framework delimits the parameters it writes into a route pattern
+///
+/// django writes `<int:pk>`; the brace form fastapi, starlette and django-bolt
+/// share writes `{pk}` or `{pk:int}`, the name and the converter the other way
+/// round. beyond the delimiters and that order, reading a pattern is the same
+/// work either way, so this is all a framework has to say about its spelling —
+/// what its converter names mean is [`Converter`]'s to say.
+#[derive(Debug, Clone, Copy)]
+struct ParameterSyntax {
+    /// what opens a parameter
+    open: char,
+    /// what closes it
+    close: char,
+    /// whether the converter is written before the name, as django writes it
+    converter_first: bool,
+    /// whether a regular expression's named groups name parameters too
+    ///
+    /// django's `re_path()` takes a regular expression rather than a pattern of
+    /// its own, and a named group in one is an argument like any other — put
+    /// through no converter, so nothing is known about its type.
+    named_groups: bool,
+}
+
+/// how django's `path()` and `re_path()` write their parameters
+const DJANGO_SYNTAX: ParameterSyntax = ParameterSyntax {
+    open: '<',
+    close: '>',
+    converter_first: true,
+    named_groups: true,
+};
+
 /// one argument a route pattern takes
 pub(crate) struct Parameter {
     pub(crate) name: CompactString,
@@ -382,6 +439,18 @@ pub(crate) struct Parameter {
     pub(crate) converter: Option<Converter>,
 }
 
+impl Parameter {
+    /// the python value the framework hands the view for this argument
+    ///
+    /// `None` where nothing here says: an argument matched by a regular
+    /// expression goes through no converter at all, and one whose converter the
+    /// project registered itself yields whatever that converter's `to_python`
+    /// returns.
+    pub(crate) fn value_type<'db>(&self, db: &'db dyn Db) -> Option<Type<'db>> {
+        self.converter?.value_type(db)
+    }
+}
+
 /// the path converters django ships
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub(crate) enum Converter {
@@ -414,6 +483,20 @@ impl Converter {
         }
     }
 
+    /// the python value the view is handed for an argument this matched
+    ///
+    /// this is the other half of what a converter is: [`Self::matches`] says what
+    /// the url may hold, and this says what comes out of `to_python` on the other
+    /// side.
+    fn value_type(self, db: &dyn Db) -> Option<Type<'_>> {
+        match self {
+            // three of django's five converters differ only in what they match
+            Self::Str | Self::Slug | Self::Path => Some(KnownClass::Str.to_instance(db)),
+            Self::Int => Some(KnownClass::Int.to_instance(db)),
+            Self::Uuid => instance_of_class(db, "uuid", "UUID"),
+        }
+    }
+
     /// whether a value written out in the template is one this would match
     pub(crate) fn matches(self, value: &str) -> bool {
         match self {
@@ -441,22 +524,33 @@ impl Converter {
     }
 }
 
-/// the arguments a route pattern names
+/// the arguments a route pattern names, read in the spelling `syntax` describes
 ///
 /// django writes them two ways: `path()` takes `<converter:name>` and
 /// `re_path()` takes a named group. a pattern with an *unnamed* group takes
 /// arguments nothing can name, so it answers nothing rather than too few.
-fn parameters_of(pattern: &str) -> Option<Vec<Parameter>> {
+fn parameters_of(pattern: &str, syntax: ParameterSyntax) -> Option<Vec<Parameter>> {
     let mut parameters = Vec::new();
     let mut rest = pattern;
 
-    while let Some(index) = rest.find(['<', '(']) {
+    let opener: &[char] = if syntax.named_groups {
+        &[syntax.open, '(']
+    } else {
+        std::slice::from_ref(&syntax.open)
+    };
+
+    while let Some(index) = rest.find(opener) {
         let after = &rest[index..];
 
-        if let Some(after) = after.strip_prefix('<') {
-            let (declaration, tail) = after.split_once('>')?;
+        if let Some(after) = after.strip_prefix(syntax.open) {
+            let (declaration, tail) = after.split_once(syntax.close)?;
             let (converter, name) = match declaration.split_once(':') {
-                Some((converter, name)) => (Converter::of(converter), name),
+                Some((converter, name)) if syntax.converter_first => {
+                    (Converter::of(converter), name)
+                }
+                Some((name, converter)) => (Converter::of(converter), name),
+                // a parameter written without a converter goes through the one
+                // that matches any single path segment
                 None => (Some(Converter::Str), declaration),
             };
             parameters.push(Parameter {
@@ -607,6 +701,20 @@ impl DiscoveredFile {
     }
 }
 
+/// whether the project has django at all
+///
+/// a project without it has no django templates: an `.html` file under a
+/// `templates` directory of a flask or a jinja project is not one, and every
+/// check reads something — the tag libraries, the template directories, the url
+/// tree — that django is what defines. asking first is also what keeps a project
+/// with no django from paying for the file-system walks the discovery does.
+#[salsa::tracked(returns(copy))]
+pub(crate) fn has_django(db: &dyn Db, _project: Project) -> bool {
+    ModuleName::new_static(DJANGO_PACKAGE)
+        .and_then(|name| resolve_module_confident(db, &name))
+        .is_some()
+}
+
 /// every file under a `templates` directory of the project, or one its settings name
 #[salsa::tracked(returns(ref), heap_size=ruff_memory_usage::heap_size)]
 pub(crate) fn template_files(db: &dyn Db, project: Project) -> Box<[DiscoveredFile]> {
@@ -2506,6 +2614,7 @@ impl UrlVisitor<'_> {
                 route: None,
                 exact: false,
                 view: None,
+                extra_arguments: false,
             },
         );
     }
@@ -2526,11 +2635,20 @@ impl UrlVisitor<'_> {
         };
 
         let route = join_routes(self.prefix.as_deref(), route_of(call).as_deref());
-        let view = call
-            .arguments
-            .args
-            .get(1)
-            .and_then(|view| resolved_target(self.db, self.file, view_callable(view)));
+        let view = call.arguments.args.get(1).and_then(|argument| {
+            let (callable, class_based) = view_callable(argument);
+
+            Some(RouteView {
+                target: resolved_target(self.db, self.file, callable)?,
+                range: callable.range(),
+                class_based,
+            })
+        });
+        // `path(route, view, kwargs, name)`: whatever the third argument holds is
+        // passed to the view alongside what the pattern captured
+        let extra_arguments =
+            call.arguments.args.len() > 2 || call.arguments.find_keyword("kwargs").is_some();
+
         self.record(
             self.binding.clone(),
             UrlName {
@@ -2540,6 +2658,7 @@ impl UrlVisitor<'_> {
                 route: route.map(|route| route.as_str().into()),
                 exact: true,
                 view,
+                extra_arguments,
             },
         );
     }
@@ -2612,7 +2731,13 @@ impl UrlVisitor<'_> {
         // a router writes its own patterns from the prefix rather than taking
         // them, so the prefix is what a route reads as but not what it takes
         let route = join_routes(self.prefix.as_deref(), Some(prefix.as_str()));
-        let view = resolved_target(self.db, self.file, viewset);
+        // a router hands each generated route `viewset.as_view({…})`, so what
+        // serves the request is one of the viewset's own methods
+        let view = resolved_target(self.db, self.file, viewset).map(|target| RouteView {
+            target,
+            range: viewset.range(),
+            class_based: true,
+        });
         let generated = |name: String, file: File, range: TextRange| UrlName {
             name: name.to_compact_string(),
             file,
@@ -2621,6 +2746,7 @@ impl UrlVisitor<'_> {
             // a router writes its own patterns rather than taking them
             exact: false,
             view: view.clone(),
+            extra_arguments: false,
         };
 
         for suffix in ROUTER_ROUTE_SUFFIXES {
@@ -2659,7 +2785,7 @@ impl UrlVisitor<'_> {
 /// makes an `@action` added to a viewset appear in a template's completions
 /// without the url configuration being touched. it costs one file per name
 /// followed, which is why it is affordable.
-fn resolved_class<T>(
+pub(crate) fn resolved_class<T>(
     db: &dyn Db,
     file: File,
     expr: &Expr,
@@ -2723,19 +2849,22 @@ fn resolved_target(db: &dyn Db, file: File, expr: &Expr) -> Option<Target> {
         })
 }
 
-/// what a route's view argument points at
+/// what a route's view argument points at, and whether it was reached through
+/// `as_view()`
 ///
 /// a class-based view is written into a route through `as_view()`, and what the
-/// route reaches is the class that method belongs to.
-fn view_callable(expr: &Expr) -> &Expr {
+/// route reaches is the class that method belongs to. that a class was reached
+/// that way is worth keeping: it is the difference between a class django calls
+/// through its handler methods and one a route hands the request to directly.
+fn view_callable(expr: &Expr) -> (&Expr, bool) {
     match expr {
         Expr::Call(call) => match &*call.func {
             Expr::Attribute(attribute) if attribute.attr.as_str() == AS_VIEW_METHOD => {
-                &attribute.value
+                (&attribute.value, true)
             }
-            _ => expr,
+            _ => (expr, false),
         },
-        _ => expr,
+        _ => (expr, false),
     }
 }
 
diff --git a/crates/ty_ide/src/django_template/routes.rs b/crates/ty_ide/src/django_template/routes.rs
new file mode 100644
index 0000000000..ac039184fe
--- /dev/null
+++ b/crates/ty_ide/src/django_template/routes.rs
@@ -0,0 +1,1303 @@
+//! what a route and the handler it names get wrong about each other
+//!
+//! a route pattern names its arguments, and the framework hands each of them to
+//! the handler by keyword when the url is requested. nothing checks the two
+//! against each other: django finds out at request time, and what it raises is a
+//! `TypeError` naming neither the route nor the view usefully.
+//!
+//! the pairing is the whole subject here, and it is not django's alone —
+//! `@api.get("/users/{user_id}")` serving an `async def get_user(user_id: int)`
+//! is the same idea in another spelling. so what varies is factored out: how a
+//! pattern writes its parameters is [`project::ParameterSyntax`]'s to say, what a
+//! converter hands the handler is [`project::Converter`]'s, and everything below
+//! works on a list of parameters and a callable. wiring a second framework up is
+//! a scan that yields routes, not a second copy of this.
+//!
+//! as everywhere else in this module, the rule is that a diagnostic must never
+//! fire on correct code. every way a handler could accept more than it appears to
+//! — a `**kwargs`, a decorator the type checker cannot see through, an inherited
+//! django handler, an extra argument the route itself passes — silences the
+//! check rather than being reported against.
+
+use compact_str::{CompactString, ToCompactString};
+use ruff_db::diagnostic::{Annotation, Diagnostic, DiagnosticId, Span};
+use ruff_db::files::File;
+use ruff_db::parsed::parsed_module;
+use ruff_python_ast::{self as ast, Stmt};
+use ruff_text_size::{Ranged, TextRange};
+use ty_project::Db;
+use ty_python_semantic::django_template::{INVALID_ROUTE_HANDLER, INVALID_ROUTE_PARAMETER_TYPE};
+use ty_python_semantic::lint::{LintId, LintMetadata};
+use ty_python_semantic::types::ide_support::{
+    CallableParameter, CallableParameterKind, callable_parameters,
+};
+use ty_python_semantic::{HasType, SemanticModel};
+
+use super::project::{self, Parameter, RouteView, TargetKind, UrlName};
+
+/// the methods a django class-based view serves a request through
+///
+/// `dispatch` and `setup` are handed the route's arguments before the method for
+/// the request's verb is, so all three see the same call. everything else a view
+/// class declares — `get_context_data`, `get_queryset` — django calls itself,
+/// with arguments of its own that have nothing to do with the route.
+const HANDLER_METHODS: &[&str] = &[
+    "get", "post", "put", "patch", "delete", "head", "options", "trace", "setup", "dispatch",
+];
+
+/// everything wrong with the routes `file` declares
+///
+/// nothing is reported unless the url tree was walked in full: a route's
+/// arguments include the ones contributed by every pattern it is mounted behind,
+/// and a walk that stopped short has read only some of them.
+pub(crate) fn diagnostics(db: &dyn Db, file: File) -> Vec<Diagnostic> {
+    if !project::routes_are_authoritative(db, db.project()) {
+        return Vec::new();
+    }
+
+    let mut found = Vec::new();
+
+    for route in project::url_names(db, db.project())
+        .iter()
+        .filter(|route| route.file == file)
+    {
+        check_route(db, file, route, &mut found);
+    }
+
+    found.sort_by_key(|diagnostic| {
+        diagnostic
+            .primary_span()
+            .and_then(|span| span.range())
+            .map(TextRange::start)
+            .unwrap_or_default()
+    });
+    found
+}
+
+/// check one route against every handler it reaches
+fn check_route(db: &dyn Db, file: File, route: &UrlName, found: &mut Vec<Diagnostic>) {
+    // a view nothing could resolve to a definition, and a pattern this could not
+    // read in full, are both routes there is nothing to say about
+    let (Some(view), Some(parameters)) = (route.view.as_ref(), route.parameters()) else {
+        return;
+    };
+
+    for handler in handlers(db, view) {
+        for complaint in handler.complaints(db, &parameters, route.extra_arguments) {
+            report(db, file, view, &handler, &complaint, found);
+        }
+    }
+}
+
+/// record one complaint, unless the rule is off or an ignore comment covers it
+///
+/// the diagnostic is anchored where the route names the view rather than at the
+/// view itself: one view may serve several routes, and it is the pairing that is
+/// wrong rather than either half. where the handler is somewhere else — a method
+/// of a view class, a function in another module — a secondary annotation points
+/// at it.
+fn report(
+    db: &dyn Db,
+    file: File,
+    view: &RouteView,
+    handler: &Handler,
+    complaint: &Complaint,
+    found: &mut Vec<Diagnostic>,
+) {
+    let lint = complaint.lint();
+    let Some(severity) = db.rule_selection(file).severity(LintId::of(lint)) else {
+        return;
+    };
+
+    let mut diagnostic = Diagnostic::new(
+        DiagnosticId::Lint(lint.name()),
+        severity,
+        format_args!("`{}` {}", handler.name, complaint.message),
+    );
+    diagnostic.annotate(Annotation::primary(Span::from(file).with_range(view.range)));
+    diagnostic.annotate(
+        Annotation::secondary(Span::from(handler.file).with_range(handler.range))
+            .message(format_args!("`{}` is declared here", handler.name)),
+    );
+    diagnostic.help(complaint.help.clone());
+
+    found.push(diagnostic);
+}
+
+/// what serves a request the route hands over
+///
+/// a function view is the one thing django calls. a class reached through
+/// `as_view()` is not called at all — what django calls is the method for the
+/// request's verb, so each of those is a handler, wherever in the class's
+/// hierarchy it is declared. what a project inherits from django needs no
+/// exception: every handler django ships takes `**kwargs`, and a `**kwargs`
+/// silences the check on its own.
+fn handlers<'db>(db: &'db dyn Db, view: &RouteView) -> Vec<Handler<'db>> {
+    let parsed = parsed_module(db, view.target.file).load(db);
+
+    let declaration = parsed
+        .suite()
+        .iter()
+        .find_map(|statement| declaration_at(statement, view.target.range));
+
+    match (view.target.kind, declaration) {
+        (TargetKind::Function, Some(Declaration::Function(function))) => {
+            Handler::of(db, view.target.file, function, None)
+                .into_iter()
+                .collect()
+        }
+        (TargetKind::Class, Some(Declaration::Class(class))) if view.class_based => HANDLER_METHODS
+            .iter()
+            .filter_map(|method| {
+                match declared_handler(db, view.target.file, class, method, MAX_BASE_DEPTH)? {
+                    Declared::Handler(handler) => Some(handler),
+                    Declared::Anything => None,
+                }
+            })
+            .collect(),
+        // a class a route hands the request to *without* `as_view()` is called
+        // rather than dispatched to, and what django would do with the result is
+        // not something this can answer
+        _ => Vec::new(),
+    }
+}
+
+/// how many base classes deep a handler is looked for
+///
+/// a project's own hierarchy is a couple deep and django's own another couple,
+/// so this is far past anything real — it is here so that a class that somehow
+/// inherits from itself stops the walk rather than running for ever.
+const MAX_BASE_DEPTH: usize = 16;
+
+/// what a class says about the method a route's request reaches
+enum Declared<'db> {
+    /// something in the hierarchy declares it, and this is what it takes
+    Handler(Handler<'db>),
+    /// something declares it and it accepts whatever it is given
+    Anything,
+}
+
+/// the declaration of `method` django would call on `class`, bases included
+///
+/// only the *first* declaration counts: a subclass overriding `get` is the one
+/// django calls and a base's is never reached, so the bases are tried in the
+/// order python resolves a member through them. a base that cannot be followed
+/// stops the search rather than being walked past — it may be the very one that
+/// declares the method, and what a search cannot see it must not report around.
+fn declared_handler<'db>(
+    db: &'db dyn Db,
+    file: File,
+    class: &ast::StmtClassDef,
+    method: &str,
+    depth: usize,
+) -> Option<Declared<'db>> {
+    if let Some(function) = class.body.iter().find_map(|statement| match statement {
+        Stmt::FunctionDef(function) if function.name.as_str() == method => Some(function),
+        _ => None,
+    }) {
+        return Some(
+            match Handler::of(db, file, function, Some(class.name.id.as_str())) {
+                Some(handler) => Declared::Handler(handler),
+                None => Declared::Anything,
+            },
+        );
+    }
+
+    if depth == 0 {
+        return Some(Declared::Anything);
+    }
+
+    for base in class.bases() {
+        let followed = project::resolved_class(db, file, base, |defining, base_class| {
+            declared_handler(db, defining, base_class, method, depth - 1)
+        });
+
+        match followed {
+            Some(Some(found)) => return Some(found),
+            // the base was read and declares nothing of the name
+            Some(None) => {}
+            None => return Some(Declared::Anything),
+        }
+    }
+
+    None
+}
+
+/// a declaration a target's name range points at
+enum Declaration<'ast> {
+    Function(&'ast ast::StmtFunctionDef),
+    Class(&'ast ast::StmtClassDef),
+}
+
+/// the declaration whose own name occupies `range`, wherever it is nested
+fn declaration_at(statement: &Stmt, range: TextRange) -> Option<Declaration<'_>> {
+    match statement {
+        Stmt::FunctionDef(function) if function.name.range() == range => {
+            Some(Declaration::Function(function))
+        }
+        Stmt::ClassDef(class) if class.name.range() == range => Some(Declaration::Class(class)),
+        Stmt::FunctionDef(function) if function.range().contains_range(range) => function
+            .body
+            .iter()
+            .find_map(|nested| declaration_at(nested, range)),
+        Stmt::ClassDef(class) if class.range().contains_range(range) => class
+            .body
+            .iter()
+            .find_map(|nested| declaration_at(nested, range)),
+        _ => None,
+    }
+}
+
+/// one callable a route's request reaches, and the parameters the route fills
+struct Handler<'db> {
+    /// what a diagnostic calls it, qualified by the view class where there is one
+    name: CompactString,
+    file: File,
+    /// the declared name, for a secondary annotation
+    range: TextRange,
+    /// every parameter after the request, which is the one django passes
+    /// positionally and no route ever names
+    parameters: Vec<CallableParameter<'db>>,
+}
+
+impl<'db> Handler<'db> {
+    /// the handler `function` is, or `None` where it accepts anything
+    ///
+    /// this is where every reason to say nothing is decided. the signature comes
+    /// from the type checker rather than from the parameter list as written, so
+    /// it is the decorated callable django will really call: a decorator that
+    /// hands back what it was given keeps the view's own parameters, and one the
+    /// type checker cannot see through leaves a signature this refuses to read.
+    fn of(
+        db: &'db dyn Db,
+        file: File,
+        function: &ast::StmtFunctionDef,
+        class: Option<&str>,
+    ) -> Option<Self> {
+        let declared = function.inferred_type(&SemanticModel::new(db, file))?;
+        let mut parameters = callable_parameters(db, declared)?;
+
+        // a method is called through the instance, which fills its receiver
+        if class.is_some() && !parameters.is_empty() {
+            parameters.remove(0);
+        }
+
+        // the request goes first and positionally, so a handler with nothing to
+        // put it in is one django cannot call at all — a different complaint,
+        // and not one a route's arguments can be held against
+        let request = parameters.first()?;
+        if !matches!(
+            request.kind,
+            CallableParameterKind::PositionalOnly | CallableParameterKind::PositionalOrKeyword
+        ) {
+            return None;
+        }
+        parameters.remove(0);
+
+        // `*args` or `**kwargs` takes whatever it is given, named or not
+        if parameters.iter().any(|parameter| {
+            matches!(
+                parameter.kind,
+                CallableParameterKind::Variadic | CallableParameterKind::KeywordVariadic
+            )
+        }) {
+            return None;
+        }
+
+        Some(Self {
+            name: match class {
+                Some(class) => format!("{class}.{}", function.name).to_compact_string(),
+                None => function.name.id.to_compact_string(),
+            },
+            file,
+            range: function.name.range(),
+            parameters,
+        })
+    }
+
+    /// everything wrong between this handler and a route giving it `parameters`
+    fn complaints(
+        &self,
+        db: &'db dyn Db,
+        parameters: &[Parameter],
+        extra_arguments: bool,
+    ) -> Vec<Complaint> {
+        let mut complaints = Vec::new();
+        let mut turned_one_down = false;
+
+        for parameter in parameters {
+            let Some(accepted) = self.by_keyword(&parameter.name) else {
+                turned_one_down = true;
+                complaints.push(Complaint {
+                    kind: ComplaintKind::Handler,
+                    message: format!("takes no argument named `{}`", parameter.name),
+                    help: "the route names it, so django passes it".to_string(),
+                });
+                continue;
+            };
+
+            // only a declared annotation is answered for: a bare parameter
+            // declares nothing, and neither does an argument matched by a regular
+            // expression rather than put through a converter
+            let (Some(converter), Some(declared)) = (parameter.converter, accepted.declared_type)
+            else {
+                continue;
+            };
+            let Some(value) = parameter.value_type(db) else {
+                continue;
+            };
+            if value.is_assignable_to(db, declared) {
+                continue;
+            }
+
+            complaints.push(Complaint {
+                kind: ComplaintKind::ParameterType,
+                message: format!("takes `{}` as `{}`", parameter.name, declared.display(db)),
+                help: format!(
+                    "the route's `{}` converter gives a `{}`",
+                    converter.name(),
+                    value.display(db)
+                ),
+            });
+        }
+
+        // a route passing arguments of its own may be filling anything the
+        // pattern says nothing about. and a name the handler already turned down
+        // is one misspelling reported once: saying it takes no `pk` *and* needs
+        // an `id` is the same mistake from both ends
+        if extra_arguments || turned_one_down {
+            return complaints;
+        }
+
+        complaints.extend(
+            self.parameters
+                .iter()
+                .filter(|parameter| !parameter.has_default)
+                .filter_map(|parameter| parameter.name.as_ref())
+                .filter(|name| !parameters.iter().any(|given| given.name == name.as_str()))
+                .map(|name| Complaint {
+                    kind: ComplaintKind::Handler,
+                    message: format!("needs an argument named `{name}`"),
+                    help: "the route names no such argument".to_string(),
+                }),
+        );
+
+        complaints
+    }
+
+    /// the parameter of this name a caller could fill by keyword
+    ///
+    /// a positional-only parameter is deliberately not one: django passes what a
+    /// pattern captured by keyword, so a name it cannot be passed under is a name
+    /// the handler does not take.
+    fn by_keyword(&self, name: &str) -> Option<&CallableParameter<'db>> {
+        self.parameters.iter().find(|parameter| {
+            matches!(
+                parameter.kind,
+                CallableParameterKind::PositionalOrKeyword | CallableParameterKind::KeywordOnly
+            ) && parameter
+                .name
+                .as_ref()
+                .is_some_and(|declared| declared.as_str() == name)
+        })
+    }
+}
+
+/// one thing wrong between a route and its handler
+struct Complaint {
+    kind: ComplaintKind,
+    message: String,
+    help: String,
+}
+
+/// which of the two rules a complaint belongs to
+enum ComplaintKind {
+    /// django cannot call the handler at all
+    Handler,
+    /// django calls it with a value its annotation says it never gets
+    ParameterType,
+}
+
+impl Complaint {
+    fn lint(&self) -> &'static LintMetadata {
+        match self.kind {
+            ComplaintKind::Handler => &INVALID_ROUTE_HANDLER,
+            ComplaintKind::ParameterType => &INVALID_ROUTE_PARAMETER_TYPE,
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use crate::django_template::tests::TemplateTest;
+
+    /// a django project whose url tree can be walked in full
+    ///
+    /// the walk is what every check here is gated on, so the settings name a
+    /// `ROOT_URLCONF` and every include below it resolves. `urls` and `views` are
+    /// the two halves under test.
+    fn project(urls: &str, views: &str) -> TemplateTest {
+        TemplateTest::with_site_packages(
+            &[
+                (
+                    "manage.py",
+                    "
+                    import os
+
+                    os.environ.setdefault('DJANGO_SETTINGS_MODULE', 'project.settings')
+                    ",
+                ),
+                ("project/__init__.py", ""),
+                (
+                    "project/settings.py",
+                    "
+                    INSTALLED_APPS = ['blog']
+
+                    TEMPLATES = [{'DIRS': [], 'APP_DIRS': True, 'OPTIONS': {}}]
+
+                    ROOT_URLCONF = 'project.urls'
+                    ",
+                ),
+                (
+                    "project/urls.py",
+                    "
+                    from django.urls import include, path
+
+                    urlpatterns = [path('blog/', include('blog.urls'))]
+                    ",
+                ),
+                ("blog/__init__.py", ""),
+                ("blog/wrappers.py", WRAPPERS),
+                ("blog/views.py", views),
+                ("blog/urls.py", urls),
+            ],
+            &[
+                ("django/__init__.py", ""),
+                ("django/urls/__init__.py", DJANGO_URLS),
+                ("django/views/__init__.py", ""),
+                ("django/views/generic/__init__.py", DJANGO_GENERIC),
+            ],
+        )
+    }
+
+    /// the two kinds of decorator a view is written behind
+    ///
+    /// one hands back what it was given and one hands back something the type
+    /// checker cannot see into, which is the whole of what decides whether a
+    /// decorated view is answered for.
+    const WRAPPERS: &str = "
+        from typing import Any
+
+
+        def passthrough[F](view: F) -> F: ...
+
+
+        def wrap(view) -> Any: ...
+        ";
+
+    /// just enough of `django.urls` for a route to be written against it
+    const DJANGO_URLS: &str = "
+        def path(route, view, kwargs=None, name=None): ...
+
+        def re_path(route, view, kwargs=None, name=None): ...
+
+        def include(arg, namespace=None): ...
+        ";
+
+    /// django's own class-based views, whose handlers all take `**kwargs`
+    const DJANGO_GENERIC: &str = "
+        class View:
+            def setup(self, request, *args, **kwargs): ...
+
+            def dispatch(self, request, *args, **kwargs): ...
+
+
+        class TemplateView(View):
+            def get(self, request, *args, **kwargs): ...
+        ";
+
+    /// the urls every test that isn't about the url configuration itself uses
+    fn urls_for(pattern: &str, view: &str) -> String {
+        format!(
+            "
+            from django.urls import path, re_path
+
+            from blog import views
+
+            app_name = 'blog'
+
+            urlpatterns = [path('{pattern}', views.{view}, name='detail')]
+            "
+        )
+    }
+
+    /// the diagnostics of a route written out in full, with its views
+    fn check_urls(urls: &str, views: &str) -> Vec<String> {
+        project(urls, views).python_diagnostics("blog/urls.py")
+    }
+
+    /// the same for the one-route case, which is most of them
+    fn check(pattern: &str, view: &str, views: &str) -> Vec<String> {
+        check_urls(&urls_for(pattern, view), views)
+    }
+
+    // ---- the pairing is right -----------------------------------------------
+
+    #[test]
+    fn a_view_taking_the_route_s_argument_by_name_and_type_is_not_reported() {
+        assert_eq!(
+            check(
+                "<int:pk>/",
+                "detail",
+                "
+                def detail(request, pk: int): ...
+                ",
+            ),
+            Vec::<String>::new()
+        );
+    }
+
+    #[test]
+    fn a_view_taking_every_argument_of_a_route_with_several_is_not_reported() {
+        assert_eq!(
+            check(
+                "<slug:slug>/<int:page>/",
+                "paged",
+                "
+                def paged(request, slug: str, page: int): ...
+                ",
+            ),
+            Vec::<String>::new()
+        );
+    }
+
+    #[test]
+    fn a_view_of_a_route_taking_nothing_is_not_reported() {
+        assert_eq!(
+            check(
+                "",
+                "index",
+                "
+                def index(request): ...
+                ",
+            ),
+            Vec::<String>::new()
+        );
+    }
+
+    // ---- the pairing is wrong -----------------------------------------------
+
+    #[test]
+    fn a_view_naming_the_argument_differently_is_reported() {
+        assert_eq!(
+            check(
+                "<int:pk>/",
+                "detail",
+                "
+                def detail(request, id: int): ...
+                ",
+            ),
+            [
+                "invalid-route-handler Error: `detail` takes no argument named `pk` \
+                 [views.detail]"
+            ]
+        );
+    }
+
+    #[test]
+    fn a_view_not_taking_the_argument_at_all_is_reported() {
+        assert_eq!(
+            check(
+                "<int:pk>/",
+                "detail",
+                "
+                def detail(request): ...
+                ",
+            ),
+            [
+                "invalid-route-handler Error: `detail` takes no argument named `pk` \
+                 [views.detail]"
+            ]
+        );
+    }
+
+    #[test]
+    fn a_view_whose_extra_parameter_has_a_default_is_not_reported() {
+        assert_eq!(
+            check(
+                "",
+                "index",
+                "
+                def index(request, category=None): ...
+                ",
+            ),
+            Vec::<String>::new(),
+            "django leaves it out and the default stands"
+        );
+    }
+
+    #[test]
+    fn a_keyword_only_parameter_is_one_a_route_can_fill() {
+        assert_eq!(
+            check(
+                "<int:pk>/",
+                "detail",
+                "
+                def detail(request, *, pk: int): ...
+                ",
+            ),
+            Vec::<String>::new(),
+            "django passes what the pattern captured by keyword"
+        );
+    }
+
+    #[test]
+    fn a_positional_only_parameter_is_one_it_cannot() {
+        assert_eq!(
+            check(
+                "<int:pk>/",
+                "detail",
+                "
+                def detail(request, pk, /): ...
+                ",
+            ),
+            ["invalid-route-handler Error: `detail` takes no argument named `pk` [views.detail]"],
+            "django passes it by keyword, and a positional-only name cannot be written"
+        );
+    }
+
+    #[test]
+    fn a_view_needing_an_argument_the_route_does_not_name_is_reported() {
+        assert_eq!(
+            check(
+                "",
+                "index",
+                "
+                def index(request, category): ...
+                ",
+            ),
+            [
+                "invalid-route-handler Error: `index` needs an argument named `category` \
+                 [views.index]"
+            ]
+        );
+    }
+
+    #[test]
+    fn a_view_declaring_a_type_the_converter_does_not_produce_is_reported() {
+        assert_eq!(
+            check(
+                "<int:pk>/",
+                "detail",
+                "
+                def detail(request, pk: str): ...
+                ",
+            ),
+            [
+                "invalid-route-parameter-type Warning: `detail` takes `pk` as `str` \
+                 [views.detail]"
+            ]
+        );
+    }
+
+    #[test]
+    fn every_converter_answers_for_the_type_it_produces() {
+        let rejected = [
+            ("<int:a>/", "a: str", "`a` as `str`"),
+            ("<str:a>/", "a: int", "`a` as `int`"),
+            ("<slug:a>/", "a: int", "`a` as `int`"),
+            ("<path:a>/", "a: int", "`a` as `int`"),
+            ("<uuid:a>/", "a: str", "`a` as `str`"),
+        ];
+
+        for (pattern, parameter, complaint) in rejected {
+            assert_eq!(
+                check(
+                    pattern,
+                    "detail",
+                    &format!(
+                        "
+                        def detail(request, {parameter}): ...
+                        "
+                    ),
+                ),
+                [format!(
+                    "invalid-route-parameter-type Warning: `detail` takes {complaint} \
+                     [views.detail]"
+                )],
+                "{pattern}"
+            );
+        }
+    }
+
+    #[test]
+    fn a_parameter_the_converter_s_value_fits_is_not_reported() {
+        let accepted = [
+            ("<int:a>/", "a: int"),
+            ("<str:a>/", "a: str"),
+            ("<slug:a>/", "a: str"),
+            ("<path:a>/", "a: str"),
+            ("<int:a>/", "a: object"),
+            ("<int:a>/", "a: int | None"),
+            ("<int:a>/", "a: float"),
+        ];
+
+        for (pattern, parameter) in accepted {
+            assert_eq!(
+                check(
+                    pattern,
+                    "detail",
+                    &format!(
+                        "
+                        def detail(request, {parameter}): ...
+                        "
+                    ),
+                ),
+                Vec::<String>::new(),
+                "{pattern}"
+            );
+        }
+    }
+
+    #[test]
+    fn a_uuid_argument_declared_as_a_uuid_is_not_reported() {
+        assert_eq!(
+            check(
+                "<uuid:key>/",
+                "detail",
+                "
+                from uuid import UUID
+
+
+                def detail(request, key: UUID): ...
+                ",
+            ),
+            Vec::<String>::new()
+        );
+    }
+
+    #[test]
+    fn a_view_serving_two_routes_is_answered_for_each_of_them() {
+        let test = project(
+            "
+            from django.urls import path
+
+            from blog import views
+
+            app_name = 'blog'
+
+            urlpatterns = [
+                path('<int:pk>/', views.listing, name='detail'),
+                path('', views.listing, name='index'),
+            ]
+            ",
+            "
+            def listing(request, pk: int): ...
+            ",
+        );
+
+        assert_eq!(
+            test.python_diagnostics("blog/urls.py"),
+            ["invalid-route-handler Error: `listing` needs an argument named `pk` [views.listing]"],
+            "the route naming nothing is served fine; the one naming `pk` is not"
+        );
+    }
+
+    // ---- a route's arguments include what it is mounted behind ---------------
+
+    #[test]
+    fn an_argument_the_including_pattern_names_is_one_the_view_has_to_take() {
+        let test = project(
+            "
+            from django.urls import path
+
+            from blog import views
+
+            app_name = 'blog'
+
+            urlpatterns = [path('reply/', views.reply, name='reply')]
+            ",
+            "
+            def reply(request): ...
+            ",
+        );
+        let mut test = test;
+        test.rewrite(
+            "project/urls.py",
+            "
+            from django.urls import include, path
+
+            urlpatterns = [path('blog/<int:pk>/', include('blog.urls'))]
+            ",
+        );
+
+        assert_eq!(
+            test.python_diagnostics("blog/urls.py"),
+            ["invalid-route-handler Error: `reply` takes no argument named `pk` [views.reply]"]
+        );
+    }
+
+    // ---- what must not fire -------------------------------------------------
+
+    #[test]
+    fn a_view_taking_keyword_variadics_is_not_reported() {
+        assert_eq!(
+            check(
+                "<int:pk>/",
+                "detail",
+                "
+                def detail(request, **kwargs): ...
+                ",
+            ),
+            Vec::<String>::new()
+        );
+    }
+
+    #[test]
+    fn a_view_taking_variadics_is_not_reported() {
+        assert_eq!(
+            check(
+                "<int:pk>/",
+                "detail",
+                "
+                def detail(request, *args): ...
+                ",
+            ),
+            Vec::<String>::new()
+        );
+    }
+
+    #[test]
+    fn an_unannotated_parameter_is_checked_by_name_and_never_by_type() {
+        assert_eq!(
+            check(
+                "<int:pk>/",
+                "detail",
+                "
+                def detail(request, pk): ...
+                ",
+            ),
+            Vec::<String>::new(),
+            "nothing declares a type, so there is no type to be wrong"
+        );
+        assert_eq!(
+            check(
+                "<int:pk>/",
+                "detail",
+                "
+                def detail(request, id): ...
+                ",
+            ),
+            ["invalid-route-handler Error: `detail` takes no argument named `pk` [views.detail]"],
+            "the name is still the name"
+        );
+    }
+
+    #[test]
+    fn a_view_reached_through_a_decorator_nothing_can_see_through_is_not_reported() {
+        assert_eq!(
+            check(
+                "<int:pk>/",
+                "detail",
+                "
+                from blog.wrappers import wrap
+
+
+                @wrap
+                def detail(request): ...
+                ",
+            ),
+            Vec::<String>::new()
+        );
+    }
+
+    #[test]
+    fn a_view_behind_a_decorator_that_hands_the_view_back_is_still_checked() {
+        let test = project(
+            &urls_for("<int:pk>/", "detail"),
+            "
+            from blog.wrappers import passthrough
+
+
+            @passthrough
+            def detail(request): ...
+            ",
+        );
+
+        assert_eq!(
+            test.python_diagnostics("blog/urls.py"),
+            ["invalid-route-handler Error: `detail` takes no argument named `pk` [views.detail]"],
+            "the decorator is typed as giving back what it was handed"
+        );
+    }
+
+    #[test]
+    fn a_route_passing_arguments_of_its_own_is_not_reported_for_needing_them() {
+        assert_eq!(
+            check_urls(
+                "
+                from django.urls import path
+
+                from blog import views
+
+                app_name = 'blog'
+
+                urlpatterns = [path('', views.index, {'category': 'books'}, name='index')]
+                ",
+                "
+                def index(request, category): ...
+                ",
+            ),
+            Vec::<String>::new()
+        );
+    }
+
+    #[test]
+    fn a_view_nothing_can_resolve_is_not_reported() {
+        assert_eq!(
+            check_urls(
+                "
+                from django.urls import path
+
+                from blog.nowhere import missing
+
+                app_name = 'blog'
+
+                urlpatterns = [path('<int:pk>/', missing, name='detail')]
+                ",
+                "
+                def detail(request): ...
+                ",
+            ),
+            Vec::<String>::new()
+        );
+    }
+
+    #[test]
+    fn a_regex_group_is_checked_by_name_and_never_by_type() {
+        assert_eq!(
+            check_urls(
+                "
+                from django.urls import re_path
+
+                from blog import views
+
+                app_name = 'blog'
+
+                urlpatterns = [
+                    re_path(r'^archive/(?P<year>[0-9]{4})/$', views.archive, name='archive'),
+                ]
+                ",
+                "
+                def archive(request, year: int): ...
+                ",
+            ),
+            Vec::<String>::new(),
+            "a group goes through no converter, so nothing says what `year` is"
+        );
+        assert_eq!(
+            check_urls(
+                "
+                from django.urls import re_path
+
+                from blog import views
+
+                app_name = 'blog'
+
+                urlpatterns = [
+                    re_path(r'^archive/(?P<year>[0-9]{4})/$', views.archive, name='archive'),
+                ]
+                ",
+                "
+                def archive(request, yr): ...
+                ",
+            ),
+            [
+                "invalid-route-handler Error: `archive` takes no argument named `year` \
+                 [views.archive]"
+            ]
+        );
+    }
+
+    #[test]
+    fn a_pattern_with_an_unnamed_group_is_not_reported() {
+        assert_eq!(
+            check_urls(
+                "
+                from django.urls import re_path
+
+                from blog import views
+
+                app_name = 'blog'
+
+                urlpatterns = [
+                    re_path(r'^archive/([0-9]{4})/$', views.archive, name='archive'),
+                ]
+                ",
+                "
+                def archive(request): ...
+                ",
+            ),
+            Vec::<String>::new(),
+            "django passes it positionally under no name at all"
+        );
+    }
+
+    #[test]
+    fn a_project_whose_url_tree_cannot_be_walked_reports_nothing() {
+        let test = project(
+            &urls_for("<int:pk>/", "detail"),
+            "
+            def detail(request): ...
+            ",
+        );
+        let mut test = test;
+        test.rewrite(
+            "project/urls.py",
+            "
+            from django.urls import include, path
+
+            urlpatterns = [path('blog/', include('nowhere.urls'))]
+            ",
+        );
+
+        assert_eq!(
+            test.python_diagnostics("blog/urls.py"),
+            Vec::<String>::new()
+        );
+    }
+
+    // ---- class-based views --------------------------------------------------
+
+    #[test]
+    fn a_class_based_view_whose_own_handler_takes_the_argument_is_not_reported() {
+        assert_eq!(
+            check(
+                "<int:pk>/",
+                "DetailView.as_view()",
+                "
+                from django.views.generic import TemplateView
+
+
+                class DetailView(TemplateView):
+                    def get(self, request, pk: int): ...
+                ",
+            ),
+            Vec::<String>::new()
+        );
+    }
+
+    #[test]
+    fn a_class_based_view_whose_own_handler_does_not_is_reported() {
+        assert_eq!(
+            check(
+                "<int:pk>/",
+                "DetailView.as_view()",
+                "
+                from django.views.generic import TemplateView
+
+
+                class DetailView(TemplateView):
+                    def get(self, request, slug): ...
+                ",
+            ),
+            [
+                "invalid-route-handler Error: `DetailView.get` takes no argument named `pk` \
+                 [views.DetailView]"
+            ]
+        );
+    }
+
+    #[test]
+    fn a_class_based_view_that_declares_no_handler_of_its_own_is_not_reported() {
+        assert_eq!(
+            check(
+                "<int:pk>/",
+                "DetailView.as_view()",
+                "
+                from django.views.generic import TemplateView
+
+
+                class DetailView(TemplateView):
+                    template_name = 'blog/detail.html'
+                ",
+            ),
+            Vec::<String>::new(),
+            "what it inherits from django takes `**kwargs`"
+        );
+    }
+
+    #[test]
+    fn a_class_based_view_whose_handler_takes_variadics_is_not_reported() {
+        assert_eq!(
+            check(
+                "<int:pk>/",
+                "DetailView.as_view()",
+                "
+                from django.views.generic import TemplateView
+
+
+                class DetailView(TemplateView):
+                    def get(self, request, *args, **kwargs): ...
+                ",
+            ),
+            Vec::<String>::new()
+        );
+    }
+
+    #[test]
+    fn a_class_based_view_s_other_methods_are_left_alone() {
+        assert_eq!(
+            check(
+                "<int:pk>/",
+                "DetailView.as_view()",
+                "
+                from django.views.generic import TemplateView
+
+
+                class DetailView(TemplateView):
+                    def get(self, request, pk: int): ...
+
+                    def get_context_data(self, **kwargs): ...
+
+                    def get_object(self): ...
+                ",
+            ),
+            Vec::<String>::new(),
+            "django calls those itself, with arguments of its own"
+        );
+    }
+
+    #[test]
+    fn a_handler_a_view_class_inherits_from_a_base_of_its_own_is_reported() {
+        assert_eq!(
+            check(
+                "<int:pk>/",
+                "DetailView.as_view()",
+                "
+                from django.views.generic import TemplateView
+
+
+                class SiteMixin(TemplateView):
+                    def get(self, request, slug): ...
+
+
+                class DetailView(SiteMixin):
+                    template_name = 'blog/detail.html'
+                ",
+            ),
+            [
+                "invalid-route-handler Error: `SiteMixin.get` takes no argument named `pk` \
+                 [views.DetailView]"
+            ],
+            "django calls the mixin's `get`, so it is the one that has to take it"
+        );
+    }
+
+    #[test]
+    fn a_handler_the_class_itself_overrides_is_the_one_answered_for() {
+        assert_eq!(
+            check(
+                "<int:pk>/",
+                "DetailView.as_view()",
+                "
+                from django.views.generic import TemplateView
+
+
+                class SiteMixin(TemplateView):
+                    def get(self, request, slug): ...
+
+
+                class DetailView(SiteMixin):
+                    def get(self, request, pk: int): ...
+                ",
+            ),
+            Vec::<String>::new(),
+            "the base's `get` is never reached"
+        );
+    }
+
+    #[test]
+    fn a_view_class_with_a_base_nothing_can_follow_is_not_reported() {
+        assert_eq!(
+            check(
+                "<int:pk>/",
+                "DetailView.as_view()",
+                "
+                from blog.nowhere import Elsewhere
+
+
+                class DetailView(Elsewhere):
+                    template_name = 'blog/detail.html'
+                ",
+            ),
+            Vec::<String>::new(),
+            "a base that cannot be read may be the one declaring the handler"
+        );
+    }
+
+    #[test]
+    fn a_class_a_route_hands_the_request_to_directly_is_not_reported() {
+        assert_eq!(
+            check(
+                "<int:pk>/",
+                "DetailView",
+                "
+                from django.views.generic import TemplateView
+
+
+                class DetailView(TemplateView):
+                    def get(self, request, slug): ...
+                ",
+            ),
+            Vec::<String>::new(),
+            "without `as_view()` django calls the class rather than dispatching to it"
+        );
+    }
+
+    // ---- silencing ----------------------------------------------------------
+
+    /// a route the view cannot serve, silenced by an ignore comment
+    const SILENCED: (&str, &str) = (
+        "
+        from django.urls import path
+
+        from blog import views
+
+        app_name = 'blog'
+
+        urlpatterns = [
+            path('<int:pk>/', views.detail, name='detail'),  # ty: ignore[invalid-route-handler]
+        ]
+        ",
+        "
+        def detail(request): ...
+        ",
+    );
+
+    #[test]
+    fn an_ignore_comment_on_the_route_silences_it() {
+        assert_eq!(
+            project(SILENCED.0, SILENCED.1).checked_python_diagnostics("blog/urls.py"),
+            Vec::<String>::new()
+        );
+    }
+
+    #[test]
+    fn an_ignore_comment_that_silenced_a_route_is_not_then_reported_unused() {
+        // the scan itself answers before any comment is read, and it is the fold into
+        // the type checker's pass that both silences the diagnostic and marks the
+        // comment used. without the second half, `unused-ignore-comment` fires on the
+        // very comment that did the silencing
+        assert_eq!(
+            check_urls(SILENCED.0, SILENCED.1),
+            ["invalid-route-handler Error: `detail` takes no argument named `pk` [views.detail]"]
+        );
+        assert!(
+            !project(SILENCED.0, SILENCED.1)
+                .checked_python_diagnostics("blog/urls.py")
+                .iter()
+                .any(|diagnostic| diagnostic.contains("unused-ignore-comment"))
+        );
+    }
+}
diff --git a/crates/ty_ide/src/django_template/symbols.rs b/crates/ty_ide/src/django_template/symbols.rs
index df8941200b..622be47058 100644
--- a/crates/ty_ide/src/django_template/symbols.rs
+++ b/crates/ty_ide/src/django_template/symbols.rs
@@ -185,7 +185,7 @@ pub(crate) fn workspace_symbols(db: &dyn Db, query: &QueryPattern) -> Vec<Django
             ));
         }
 
-        if let Some(view) = &route.view
+        if let Some(view) = route.view.as_ref().map(|view| &view.target)
             && query.is_match_symbol_name(&view.name)
             && seen.insert((view.file, view.range))
         {
diff --git a/crates/ty_ide/src/lib.rs b/crates/ty_ide/src/lib.rs
index c901f2171f..f9efae395d 100644
--- a/crates/ty_ide/src/lib.rs
+++ b/crates/ty_ide/src/lib.rs
@@ -41,12 +41,13 @@ pub use completion::{
     CompletionSettings, completion,
 };
 pub use django_template::{
-    DisplayTemplateHover, DjangoCodeLens, DjangoLensAction, DjangoLensTarget, DjangoSymbol,
-    PreparedTemplateRename, TemplateCompletion, TemplateEdit, TemplateHover, TemplateInlayHint,
-    TemplateInlayHintKind, TemplateRename, TemplateRenameOutcome, TemplateSignature,
-    TemplateSymbol, django_manage_script, django_prepare_rename, django_python_code_lenses,
-    django_references, django_rename, django_template_code_lenses, django_template_completions,
-    django_template_diagnostics, django_template_document_symbols, django_template_folding_ranges,
+    DisplayTemplateHover, DjangoChecker, DjangoCodeLens, DjangoLensAction, DjangoLensTarget,
+    DjangoSymbol, PreparedTemplateRename, TemplateCompletion, TemplateEdit, TemplateHover,
+    TemplateInlayHint, TemplateInlayHintKind, TemplateRename, TemplateRenameOutcome,
+    TemplateSignature, TemplateSymbol, django_manage_script, django_prepare_rename,
+    django_python_code_lenses, django_python_diagnostics, django_references, django_rename,
+    django_template_code_lenses, django_template_completions, django_template_diagnostics,
+    django_template_document_symbols, django_template_folding_ranges,
     django_template_goto_definition, django_template_hover, django_template_inlay_hints,
     django_template_semantic_tokens, django_template_signature_help, is_django_template_path,
 };
diff --git a/crates/ty_project/src/db.rs b/crates/ty_project/src/db.rs
index bf3da3a637..65bfcf0ec9 100644
--- a/crates/ty_project/src/db.rs
+++ b/crates/ty_project/src/db.rs
@@ -6,7 +6,7 @@ use std::{cmp, fmt};
 pub use self::changes::ChangeResult;
 use crate::CollectReporter;
 use crate::metadata::settings::file_settings;
-use crate::{ProgressReporter, Project, ProjectMetadata};
+use crate::{ProgressReporter, Project, ProjectChecker, ProjectMetadata};
 use get_size2::StandardTracker;
 use ruff_db::Db as SourceDb;
 use ruff_db::diagnostic::Diagnostic;
@@ -28,6 +28,12 @@ pub trait Db: SemanticDb {
     fn project(&self) -> Project;
 
     fn dyn_clone(&self) -> Box<dyn Db>;
+
+    /// The checker for the part of the project that is not Python, if one is
+    /// registered. See [`ProjectChecker`].
+    fn project_checker(&self) -> Option<&dyn ProjectChecker> {
+        None
+    }
 }
 
 /// Tracked so that a change to the open-file set only invalidates queries
@@ -56,6 +62,11 @@ pub struct ProjectDatabase {
     // or the "trick" to get a mutable `Arc` in `Self::system_mut` is no longer guaranteed to work.
     system: Arc<dyn System + Send + Sync + RefUnwindSafe>,
 
+    // Deliberately not a Salsa input: it is set once before the first check and never
+    // changes, so nothing that reads it can go stale, and every handle the parallel
+    // check clones keeps it.
+    checker: Option<Arc<dyn ProjectChecker>>,
+
     // IMPORTANT: This field must be the last because we use `trigger_cancellation` (drops all other storage references)
     // to drop all other references to the database, which gives us exclusive access to other `Arc`s stored on this db.
     // However, for this to work it's important that the `storage` is dropped AFTER any `Arc` that
@@ -127,6 +138,7 @@ impl ProjectDatabase {
             }),
             files: Files::default(),
             system: Arc::new(system),
+            checker: None,
         };
 
         // TODO: Use the `program_settings` to compute the key for the database's persistent
@@ -190,6 +202,14 @@ impl ProjectDatabase {
         crate::check_file(self, file)
     }
 
+    /// Registers the checker for the part of the project that is not Python.
+    ///
+    /// Must be called before the first check: it is not a Salsa input, so a checker
+    /// registered later does not invalidate anything already computed.
+    pub fn set_checker(&mut self, checker: Arc<dyn ProjectChecker>) {
+        self.checker = Some(checker);
+    }
+
     /// Set the check mode for the project.
     pub fn set_check_mode(&mut self, mode: CheckMode) {
         if self.project().check_mode(self) != mode {
@@ -617,6 +637,10 @@ impl Db for ProjectDatabase {
     fn dyn_clone(&self) -> Box<dyn Db> {
         Box::new(self.clone())
     }
+
+    fn project_checker(&self) -> Option<&dyn ProjectChecker> {
+        self.checker.as_deref()
+    }
 }
 
 #[cfg(feature = "format")]
diff --git a/crates/ty_project/src/lib.rs b/crates/ty_project/src/lib.rs
index 726f20d5c0..764fdace77 100644
--- a/crates/ty_project/src/lib.rs
+++ b/crates/ty_project/src/lib.rs
@@ -134,6 +134,48 @@ pub struct Project {
     pub file_system_revision: u64,
 }
 
+/// A checker for the part of a project the type checker does not read.
+///
+/// The type checker reads Python. A project can hold files of another language
+/// that are still part of it — a Django template is compiled and rendered rather
+/// than typed — and what such a file gets wrong is worked out somewhere that has
+/// read the whole project rather than the file on its own.
+///
+/// Registering one of these with [`ProjectDatabase::set_checker`] joins it to
+/// [`Project::check`], which stays the single place that knows how to check a
+/// project: the extra files go through the same parallel loop, the same
+/// [`ProgressReporter`], and the same output formats and exit codes, and an editor
+/// registering the same checker reports exactly what the command line does.
+///
+/// A project the checker has nothing to say about must answer `files` with an
+/// empty set: nothing else is called for such a project, so it pays nothing.
+pub trait ProjectChecker: Send + Sync + std::panic::RefUnwindSafe {
+    /// Whether `path` is this checker's rather than the type checker's.
+    ///
+    /// A file this answers `true` for is kept out of the project's file set even
+    /// when it was named on the command line, which is otherwise taken to mean
+    /// "analyze this whatever its extension is". Reading a Django template as
+    /// Python produces a page of syntax errors about a file that is not Python.
+    fn owns(&self, db: &dyn Db, path: &SystemPath) -> bool;
+
+    /// The project's files this checker answers for.
+    ///
+    /// None of them is in the project's file set — the type checker must never be
+    /// handed one — so this is the only thing that says they exist.
+    fn files(&self, db: &dyn Db) -> Vec<File>;
+
+    /// Everything wrong with `file`, which is one of [`Self::files`].
+    fn check_file(&self, db: &dyn Db, file: File) -> Vec<Diagnostic>;
+
+    /// What this checker has to say about a Python file of the project.
+    ///
+    /// Returned with the file's suppression comments *not* applied: they are
+    /// applied where the type checker applies its own (see
+    /// [`ty_python_semantic::check_file_with`]), so that one `ty: ignore`
+    /// silences either kind of diagnostic and counts as used either way.
+    fn check_python_file(&self, db: &dyn Db, file: File) -> Vec<Diagnostic>;
+}
+
 /// A progress reporter.
 pub trait ProgressReporter: Send + Sync {
     /// Initialize the reporter with the number of files.
@@ -385,7 +427,15 @@ impl Project {
             .collect();
 
         let files = ProjectFiles::new(db, self);
-        reporter.set_files(files.len());
+
+        // the project's files that are not python. a django template is never handed
+        // to the type checker — it is not in the file set above and is never parsed as
+        // python — but it is part of the project, so it is checked here
+        let checker = db.project_checker();
+        let other_language: Vec<File> =
+            checker.map(|checker| checker.files(db)).unwrap_or_default();
+
+        reporter.set_files(files.len() + other_language.len());
 
         diagnostics.extend_from_slice(files.diagnostics());
 
@@ -428,6 +478,20 @@ impl Project {
                 }
             });
 
+        if let Some(checker) = checker {
+            other_language
+                .into_par_iter()
+                .for_each_with_project_db(db, |db, file| {
+                    db.unwind_if_revision_cancelled();
+
+                    let check_file_span =
+                        tracing::debug_span!(parent: &project_span, "check_file", ?file);
+                    let _entered = check_file_span.entered();
+
+                    reporter.report_checked_file(db, file, &checker.check_file(db, file));
+                });
+        }
+
         tracing::debug!(
             "Checking all files took {:.3}s",
             check_start.elapsed().as_secs_f64(),
@@ -754,7 +818,17 @@ pub enum ProjectReloadResult {
 pub(crate) fn check_file_impl(db: &dyn Db, file: File) -> Result<Box<[Diagnostic]>, Diagnostic> {
     {
         let db = AssertUnwindSafe(db);
-        match catch(&**db, file, || ty_python_semantic::check_file(*db, file)) {
+        match catch(&**db, file, || {
+            // what a registered checker has to say about a python file is folded into
+            // the type checker's own pass rather than reported beside it, so that the
+            // file's suppression comments apply to both alike
+            let external = db
+                .project_checker()
+                .map(|checker| checker.check_python_file(*db, file))
+                .unwrap_or_default();
+
+            ty_python_semantic::check_file_with(*db, file, external)
+        }) {
             Ok(result) => result,
             Err(diagnostic) => Ok(Box::new([diagnostic])),
         }
diff --git a/crates/ty_project/src/walk.rs b/crates/ty_project/src/walk.rs
index 6efea29574..98e4041549 100644
--- a/crates/ty_project/src/walk.rs
+++ b/crates/ty_project/src/walk.rs
@@ -256,6 +256,18 @@ impl ProjectFilesWalker {
                                 }
                             }
 
+                            // A file another language owns is never handed to the type checker,
+                            // not even when it was named on the command line — the branch above
+                            // takes an explicitly passed path to be something ty can analyze,
+                            // and a Django template read as Python is a page of syntax errors.
+                            // It is still checked, by the checker that owns it.
+                            if db
+                                .project_checker()
+                                .is_some_and(|checker| checker.owns(&*db, entry.path()))
+                            {
+                                return WalkState::Skip;
+                            }
+
                             // If this returns `Err`, then the file was deleted between now and when the walk callback was called.
                             // We can ignore this.
                             if let Ok(file) = system_path_to_file(&*db, entry.path()) {
diff --git a/crates/ty_python_semantic/src/django_template.rs b/crates/ty_python_semantic/src/django_template.rs
index 2bd60812ac..3f0e7357a5 100644
--- a/crates/ty_python_semantic/src/django_template.rs
+++ b/crates/ty_python_semantic/src/django_template.rs
@@ -1,10 +1,14 @@
-//! the lints a django template can report
+//! the lints django support can report
 //!
-//! a template is not python, so nothing here checks anything: the checks live in
-//! `ty_ide`'s template front end, which is the only place that can read a
-//! template at all. what has to live here is the *declaration* of each rule,
-//! because the lint registry — and with it `[tool.ty.rules]`, the generated
-//! schema and the generated documentation — is this crate's.
+//! nothing here checks anything: the checks live in `ty_ide`'s django front end,
+//! which is the only place that has read the project's templates and its url
+//! tree. what has to live here is the *declaration* of each rule, because the
+//! lint registry — and with it `[tool.ty.rules]`, the generated schema and the
+//! generated documentation — is this crate's.
+//!
+//! most of them are a template's, and the last two are the python side of the
+//! same join: a route pattern names the arguments django will hand the view, and
+//! the view has to be able to take them.
 
 use crate::declare_lint;
 use crate::lint::{Level, LintRegistryBuilder, LintStatus};
@@ -23,6 +27,8 @@ pub(crate) fn register_lints(registry: &mut LintRegistryBuilder) {
     registry.register_lint(&INVALID_ROUTE_ARGUMENTS);
     registry.register_lint(&UNKNOWN_TEMPLATE_BLOCK);
     registry.register_lint(&TEMPLATE_MEMBER_NEEDS_ARGUMENTS);
+    registry.register_lint(&INVALID_ROUTE_HANDLER);
+    registry.register_lint(&INVALID_ROUTE_PARAMETER_TYPE);
 }
 
 declare_lint! {
@@ -313,3 +319,72 @@ declare_lint! {
         default_level: Level::Warn,
     }
 }
+
+declare_lint! {
+    /// ## What it does
+    /// Checks that the view a route names can take the arguments the route's
+    /// pattern gives it.
+    ///
+    /// ## Why is this bad?
+    /// A route pattern names its arguments, and django hands each of them to the
+    /// view as a keyword argument. A view that names them differently, or does
+    /// not take them at all, raises `TypeError` when the url is requested — a
+    /// failure nothing reports until the page 500s.
+    ///
+    /// Only a project whose url tree could be walked in full is checked, since a
+    /// route's arguments include the ones the patterns it is mounted behind
+    /// contribute. A view taking `*args` or `**kwargs` accepts anything and is
+    /// never reported, nor is one reached through a decorator the type checker
+    /// cannot see through. A class-based view is checked through the handler
+    /// methods it declares itself: what it inherits from django takes `**kwargs`.
+    ///
+    /// ## Examples
+    /// ```python
+    /// path("books/<int:pk>/", views.detail, name="detail")
+    /// ```
+    ///
+    /// ```python
+    /// def detail(request, id): ...     # error: the route names `pk`
+    /// def detail(request): ...         # error: `pk` has nowhere to go
+    /// def detail(request, pk): ...     # ok
+    /// ```
+    pub static INVALID_ROUTE_HANDLER = {
+        summary: "detects a view that cannot take the arguments its route gives it",
+        status: LintStatus::stable("0.0.69"),
+        default_level: Level::Error,
+    }
+}
+
+declare_lint! {
+    /// ## What it does
+    /// Checks the type a view declares for a route argument against the type the
+    /// route's converter produces.
+    ///
+    /// ## Why is this bad?
+    /// A path converter parses the url before django calls the view:
+    /// `<int:pk>` hands the view an `int` and `<uuid:key>` a `uuid.UUID`. A view
+    /// declaring something else is annotated with a type its argument never has,
+    /// so everything written against the annotation is written against a value
+    /// that is not there.
+    ///
+    /// Unlike `invalid-route-handler` this does not stop the request: django
+    /// calls the view and the wrong value arrives silently.
+    /// An unannotated parameter declares nothing and is never reported,
+    /// and neither is one matched by a regular expression, which goes through no
+    /// converter at all.
+    ///
+    /// ## Examples
+    /// ```python
+    /// path("books/<int:pk>/", views.detail, name="detail")
+    /// ```
+    ///
+    /// ```python
+    /// def detail(request, pk: str): ...    # warning: the converter gives an `int`
+    /// def detail(request, pk: int): ...    # ok
+    /// ```
+    pub static INVALID_ROUTE_PARAMETER_TYPE = {
+        summary: "detects a view declaring a type its route's converter does not produce",
+        status: LintStatus::stable("0.0.69"),
+        default_level: Level::Warn,
+    }
+}
diff --git a/crates/ty_python_semantic/src/lib.rs b/crates/ty_python_semantic/src/lib.rs
index 498460021c..bef4745b8e 100644
--- a/crates/ty_python_semantic/src/lib.rs
+++ b/crates/ty_python_semantic/src/lib.rs
@@ -7,7 +7,7 @@ use crate::suppression::{
     BLANKET_IGNORE_COMMENT, IGNORE_COMMENT_UNKNOWN_RULE, INVALID_IGNORE_COMMENT,
     UNUSED_TYPE_IGNORE_COMMENT,
 };
-use crate::types::check_types;
+use crate::types::check_types_with;
 pub use db::Db;
 pub use diagnostic::{
     add_inferred_python_version_hint_to_diagnostic, inferred_python_version_source_annotation,
@@ -326,7 +326,23 @@ pub fn check_file_unwrap(db: &dyn Db, file: File) -> Vec<Diagnostic> {
 }
 
 pub fn check_file(db: &dyn Db, file: File) -> Result<Box<[Diagnostic]>, Diagnostic> {
-    with_display_for_file(db, file, || check_file_inner(db, file))
+    check_file_with(db, file, Vec::new())
+}
+
+/// [`check_file`], with lint diagnostics worked out elsewhere folded in.
+///
+/// `external` are diagnostics about `file` that this crate cannot compute — the
+/// django route checks read the project's whole url tree, which is not something
+/// a pass over one file can see. They arrive with the file's suppression comments
+/// *not* applied, so that applying them happens here alongside the type checker's
+/// own: one `ty: ignore` then silences either kind of diagnostic, and counts as
+/// used either way.
+pub fn check_file_with(
+    db: &dyn Db,
+    file: File,
+    external: Vec<Diagnostic>,
+) -> Result<Box<[Diagnostic]>, Diagnostic> {
+    with_display_for_file(db, file, || check_file_inner(db, file, external))
 }
 
 /// Run `body` with the type display `file` is written in: basedpython surface
@@ -344,7 +360,11 @@ pub fn with_display_for_file<R>(db: &dyn Db, file: File, body: impl FnOnce() ->
     }
 }
 
-fn check_file_inner(db: &dyn Db, file: File) -> Result<Box<[Diagnostic]>, Diagnostic> {
+fn check_file_inner(
+    db: &dyn Db,
+    file: File,
+    external: Vec<Diagnostic>,
+) -> Result<Box<[Diagnostic]>, Diagnostic> {
     let mut diagnostics: Vec<Diagnostic> = Vec::new();
 
     // Abort checking if there are IO errors.
@@ -374,7 +394,7 @@ fn check_file_inner(db: &dyn Db, file: File) -> Result<Box<[Diagnostic]>, Diagno
         error
     }));
 
-    diagnostics.extend(check_types(db, file));
+    diagnostics.extend(check_types_with(db, file, external));
 
     diagnostics.sort_unstable_by(|a, b| a.rendering_sort_key(db).cmp(&b.rendering_sort_key(db)));
 
diff --git a/crates/ty_python_semantic/src/types.rs b/crates/ty_python_semantic/src/types.rs
index 97840e8bdc..387df02194 100644
--- a/crates/ty_python_semantic/src/types.rs
+++ b/crates/ty_python_semantic/src/types.rs
@@ -62,7 +62,7 @@ use crate::place::{
     builtins_module_scope, imported_symbol, known_module_symbol, place_from_bindings,
 };
 use crate::semantic_model::NameKind;
-use crate::suppression::check_suppressions;
+use crate::suppression::{check_suppressions, suppressions};
 use crate::types::bound_super::BoundSuperType;
 use crate::types::call::bind::ConstructorCallableKind;
 use crate::types::call::{Binding, Bindings, CallArguments, CallableBinding};
@@ -233,6 +233,18 @@ mod property_tests;
 mod subscript;
 
 pub fn check_types(db: &dyn Db, file: File) -> Vec<Diagnostic> {
+    check_types_with(db, file, Vec::new())
+}
+
+/// [`check_types`], with lint diagnostics worked out elsewhere folded in.
+///
+/// See [`crate::check_file_with`] for what `external` is and why its suppressions
+/// are applied here rather than where it was computed.
+pub(crate) fn check_types_with(
+    db: &dyn Db,
+    file: File,
+    external: Vec<Diagnostic>,
+) -> Vec<Diagnostic> {
     let _span = tracing::trace_span!("check_types", ?file).entered();
     tracing::debug!("Checking file '{path}'", path = file.path(db));
 
@@ -262,6 +274,8 @@ pub fn check_types(db: &dyn Db, file: File) -> Vec<Diagnostic> {
             .map(|error| Diagnostic::invalid_syntax(file, error, error)),
     );
 
+    report_external(db, file, external, &mut diagnostics);
+
     let diagnostics = check_suppressions(db, file, diagnostics);
 
     let elapsed = start.elapsed();
@@ -275,6 +289,39 @@ pub fn check_types(db: &dyn Db, file: File) -> Vec<Diagnostic> {
     diagnostics
 }
 
+/// Apply `file`'s suppression comments to diagnostics computed outside this crate.
+///
+/// A suppressed one is dropped and the comment that silenced it marked used, both
+/// exactly as for a diagnostic the type checker raised itself. The marking is the
+/// point: without it `unused-ignore-comment` reports the very comment that did the
+/// silencing.
+fn report_external(
+    db: &dyn Db,
+    file: File,
+    external: Vec<Diagnostic>,
+    diagnostics: &mut TypeCheckDiagnostics,
+) {
+    if external.is_empty() {
+        return;
+    }
+
+    let suppressions = suppressions(db, file);
+
+    for diagnostic in external {
+        let suppression = diagnostic
+            .id()
+            .as_lint()
+            .and_then(|name| db.lint_registry().get(name.as_str()).ok())
+            .zip(diagnostic.primary_span().and_then(|span| span.range()))
+            .and_then(|(lint, range)| suppressions.find_suppression(range, lint));
+
+        match suppression {
+            Some(suppression) => diagnostics.mark_used(suppression.id()),
+            None => diagnostics.push(diagnostic),
+        }
+    }
+}
+
 /// Infer the type of a binding.
 pub(crate) fn binding_type<'db>(db: &'db dyn Db, definition: Definition<'db>) -> Type<'db> {
     let inference = infer_definition_types(db, definition);
diff --git a/crates/ty_python_semantic/src/types/ide_support.rs b/crates/ty_python_semantic/src/types/ide_support.rs
index 88b3b65126..cc81fc0d8f 100644
--- a/crates/ty_python_semantic/src/types/ide_support.rs
+++ b/crates/ty_python_semantic/src/types/ide_support.rs
@@ -1,7 +1,7 @@
 use std::collections::HashMap;
 
 use crate::FxIndexSet;
-use crate::place::builtins_module_scope;
+use crate::place::{builtins_module_scope, imported_symbol};
 use crate::reachability::is_range_reachable;
 use crate::types::call::bind::CheckTypesMode;
 use crate::types::call::{CallArguments, CallError, MatchedArgument};
@@ -11,7 +11,7 @@ use crate::types::function::FunctionDecorators;
 use crate::types::generics::GenericContext;
 use crate::types::list_members::all_end_of_scope_members;
 use crate::types::overrides::is_constructor_like_method;
-use crate::types::signatures::{ParametersKind, Signature};
+use crate::types::signatures::{ParameterKind, ParametersKind, Signature};
 use crate::types::{
     CallDunderError, CallableTypes, ClassBase, ClassLiteral, ClassType, KnownClass, KnownFunction,
     KnownUnion, SubclassOfInner, Type, TypeContext, TypeVarVariance, binding_type,
@@ -25,7 +25,7 @@ use ruff_python_ast::{self as ast, AnyNodeRef, name::Name};
 use ruff_python_stdlib::identifiers::is_mangled_private;
 use ruff_text_size::{Ranged, TextRange};
 use rustc_hash::FxHashSet;
-use ty_module_resolver::Module;
+use ty_module_resolver::{Module, ModuleName, resolve_module_confident};
 use ty_python_core::definition::{Definition, DefinitionKind};
 use ty_python_core::{attribute_scopes, global_scope, semantic_index, use_def_map};
 
@@ -2463,6 +2463,106 @@ pub fn no_argument_call_return_type<'db>(db: &'db dyn Db, ty: Type<'db>) -> Opti
         .map(|bindings| bindings.return_type(db))
 }
 
+/// How a callable takes one of its parameters.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum CallableParameterKind {
+    /// `def f(x, /)`
+    PositionalOnly,
+    /// `def f(x)`
+    PositionalOrKeyword,
+    /// `def f(*args)`
+    Variadic,
+    /// `def f(*, x)`
+    KeywordOnly,
+    /// `def f(**kwargs)`
+    KeywordVariadic,
+}
+
+/// One parameter of a callable, read the way a caller reasoning about a call
+/// site written elsewhere has to read it.
+#[derive(Debug, Clone)]
+pub struct CallableParameter<'db> {
+    pub name: Option<Name>,
+    pub kind: CallableParameterKind,
+    /// The type the parameter is declared with, or `None` where nothing declares
+    /// one — an unannotated parameter accepts whatever it is given.
+    pub declared_type: Option<Type<'db>>,
+    /// Whether a call may leave the parameter out.
+    pub has_default: bool,
+}
+
+/// The parameters `ty` takes, for a callable that takes one fixed list of them.
+///
+/// Returns `None` for everything else: a type that is not callable at all, an
+/// overloaded one, a union of callables, and one whose parameters are gradual
+/// (`Callable[..., T]`, which is what an undecipherable decorator leaves behind).
+/// None of those has a single parameter list to answer with, and a caller
+/// checking a call site written in another language has to be able to tell "this
+/// callable does not take that" from "there is no saying what this takes".
+///
+/// Written for the web frameworks, whose routes name the arguments a request
+/// hands the view. The signature this returns is the one the framework will call,
+/// decorators applied — a decorator the type checker can see through keeps the
+/// view's own parameters, and one it cannot leaves parameters this refuses to
+/// answer for.
+pub fn callable_parameters<'db>(
+    db: &'db dyn Db,
+    ty: Type<'db>,
+) -> Option<Vec<CallableParameter<'db>>> {
+    let callable = ty
+        .try_upcast_to_callable(db)
+        .and_then(CallableTypes::exactly_one)?;
+    let signatures = callable.signatures(db);
+    let [signature] = signatures.overloads.as_slice() else {
+        return None;
+    };
+
+    let parameters = signature.parameters();
+    if !matches!(parameters.kind(), ParametersKind::Standard) {
+        return None;
+    }
+
+    Some(
+        parameters
+            .iter()
+            .map(|parameter| CallableParameter {
+                name: parameter.name().cloned(),
+                kind: match parameter.kind() {
+                    ParameterKind::PositionalOnly { .. } => CallableParameterKind::PositionalOnly,
+                    ParameterKind::PositionalOrKeyword { .. } => {
+                        CallableParameterKind::PositionalOrKeyword
+                    }
+                    ParameterKind::Variadic { .. } => CallableParameterKind::Variadic,
+                    ParameterKind::KeywordOnly { .. } => CallableParameterKind::KeywordOnly,
+                    ParameterKind::KeywordVariadic { .. } => CallableParameterKind::KeywordVariadic,
+                },
+                // an annotation the type checker inferred rather than read is no
+                // declaration: the parameter was written bare, and a bare
+                // parameter accepts whatever the caller passes
+                declared_type: (parameter.should_annotation_be_displayed()
+                    && !parameter.annotated_type().is_unknown())
+                .then(|| parameter.annotated_type()),
+                has_default: parameter.default_type().is_some(),
+            })
+            .collect(),
+    )
+}
+
+/// The instance type of the class `name` of the module `module`, where the
+/// environment has it.
+///
+/// Written for the web frameworks, which say what a route hands a view by naming
+/// the class — django's `<uuid:key>` is a `uuid.UUID` — rather than by writing a
+/// type expression anywhere the type checker would evaluate one.
+pub fn instance_of_class<'db>(db: &'db dyn Db, module: &str, name: &str) -> Option<Type<'db>> {
+    let module = resolve_module_confident(db, &ModuleName::new(module)?)?;
+
+    imported_symbol(db, module.file(db), name, None)
+        .place
+        .ignore_possibly_undefined()?
+        .to_instance_approximation(db)
+}
+
 /// Whether `ty` is a function django would try to call and could not.
 ///
 /// Written for django templates, which render `string_if_invalid` — the empty
diff --git a/crates/ty_server/src/server/api/diagnostics.rs b/crates/ty_server/src/server/api/diagnostics.rs
index 57535cc52a..960070cb32 100644
--- a/crates/ty_server/src/server/api/diagnostics.rs
+++ b/crates/ty_server/src/server/api/diagnostics.rs
@@ -412,7 +412,12 @@ pub(super) fn compute_diagnostics(
         });
     }
 
+    // what django's routes and views get wrong is read from the project's url tree
+    // rather than from this file alone, so it is not part of the type checker's own
+    // pass. it arrives here through the checker the session registers, which is the
+    // one `by check` registers too
     let diagnostics = db.check_file(file);
+
     let unnecessary_hints = hints(db, file);
 
     Some(Diagnostics {
diff --git a/crates/ty_server/src/session.rs b/crates/ty_server/src/session.rs
index aa28a20443..6891d13201 100644
--- a/crates/ty_server/src/session.rs
+++ b/crates/ty_server/src/session.rs
@@ -611,7 +611,7 @@ impl Session {
                 ProjectDatabase::fallible(metadata, system.clone())
             });
 
-        let (root, db) = match project {
+        let (root, mut db) = match project {
             Ok(db) => (root, db),
             Err(err) => {
                 tracing::error!(
@@ -640,6 +640,11 @@ impl Session {
             }
         };
 
+        // the same checker `by check` registers, so that a python file's django
+        // diagnostics reach the editor through `check_file` — one set of rules, one
+        // set of suppressions
+        db.set_checker(Arc::new(ty_ide::DjangoChecker));
+
         // Carry forward diagnostic state if any exists
         let previous = self.projects.remove(&root);
         let untracked = previous
diff --git a/docs/basedpython/frameworks/django-templates.md b/docs/basedpython/frameworks/django-templates.md
index 2203971281..bf73e3761f 100644
--- a/docs/basedpython/frameworks/django-templates.md
+++ b/docs/basedpython/frameworks/django-templates.md
@@ -76,6 +76,8 @@ a `{% for book in shelf %}` shows the element type it binds, which is what says
 
 **diagnostics.** a template reports twelve rules — an unclosed block, an unknown tag or filter, a tag used without its `{% load %}`, a missing template or static file, an unknown route or the wrong arguments to one, a block no ancestor declares, and a member django cannot call. each is silent unless the index behind it is authoritative, so a project whose settings cannot be read reports nothing rather than guessing. silence one with `{# ty: ignore #}` or `{# ty: ignore[rule-name] #}`, or configure it under `[tool.ty.rules]` like any other.
 
+`by check` reports them too. a template is not in the project's python file set and is never read as python — it is checked as the template it is — but it is part of the project, so the command line and the editor say the same thing about the same file. only the project's own templates are checked; an installed app's are a dependency's source, and a project with no django has no django templates.
+
 an unknown *variable* is still not reported: a context can come from places a scan cannot see, so absence is not evidence.
 
 ### the project's django structure
@@ -100,6 +102,29 @@ the function is matched by its last segment, so `shortcuts.render` and `render`
 
 `redirect()` takes a url or a model as readily as a route name, so a string with a `/` in it is left alone entirely and a name the url configuration doesn't have leads nowhere.
 
+### a route and the view it names
+
+a route pattern names its arguments and django hands each of them to the view by keyword. the two are checked against each other:
+
+```py
+path("books/<int:pk>/", views.detail, name="detail")
+
+def detail(request, pk: int): ...   # correct
+def detail(request, id: int): ...   # invalid-route-handler: the route names `pk`
+def detail(request): ...            # invalid-route-handler: `pk` has nowhere to go
+def detail(request, pk: str): ...   # invalid-route-parameter-type: the converter gives an `int`
+```
+
+the first two are a `TypeError` when the url is requested; the last is a value that arrives with a type its annotation denies.
+
+what a route gives its view includes what every pattern it is mounted behind names, so an `include('blog.urls')` written under `books/<int:pk>/` puts `pk` in front of every view below it. the check therefore runs only where the url tree could be walked in full.
+
+nothing is reported for a view that could accept more than it appears to: one taking `*args` or `**kwargs`, one reached through a decorator the type checker cannot see through, one nothing can resolve to a definition, or a route passing extra arguments of its own through `path()`'s third argument. an argument matched by a `re_path()` group goes through no converter, so its name is checked and its type never is.
+
+a class-based view is reached through `as_view()`, which django calls rather than the class — so what has to take the route's arguments is `get`, `post`, `dispatch` and the rest. only the ones the class declares itself are checked: every handler django ships takes `**kwargs`, so an inherited one accepts anything.
+
+these two read the whole url tree rather than the one file, which is not something the type checker's own pass can do, but they arrive with what it found: `by check` and the editor both report them, and a `# ty: ignore[invalid-route-handler]` on the route silences one and counts as used, exactly as it would for a type error.
+
 ## how a template's variables are found
 
 the chain runs from the template back to the type checker:
@@ -206,6 +231,10 @@ a project whose settings cannot be read, or whose django cannot be resolved at a
 
 **a name written in python has to be a literal.** the string in a `render()` or a `reverse()` is read as it is written, so a name built from an f-string, or held in a variable, is just a string.
 
+**only a route the configuration names is paired with its view.** the route index is built out of the names a `{% url %}` reverses, so a `path("books/<int:pk>/", views.detail)` written without a `name=` is not checked against `views.detail`.
+
+**neither `--fix` nor `--add-ignore` touches a template.** both rewrite a file through its python tokens, and a template has none. a template diagnostic is reported unchanged by either, and a `{# ty: ignore #}` has to be written by hand — or taken from the quick fix the editor offers.
+
 ## see also
 
 - [django support](django.md) — the type checker's understanding of models, fields and queries
diff --git a/ty.schema.json b/ty.schema.json
index 02787c5598..6c11540744 100644
--- a/ty.schema.json
+++ b/ty.schema.json
@@ -1220,6 +1220,26 @@
             }
           ]
         },
+        "invalid-route-handler": {
+          "title": "detects a view that cannot take the arguments its route gives it",
+          "description": "## What it does\nChecks that the view a route names can take the arguments the route's\npattern gives it.\n\n## Why is this bad?\nA route pattern names its arguments, and django hands each of them to the\nview as a keyword argument. A view that names them differently, or does\nnot take them at all, raises `TypeError` when the url is requested — a\nfailure nothing reports until the page 500s.\n\nOnly a project whose url tree could be walked in full is checked, since a\nroute's arguments include the ones the patterns it is mounted behind\ncontribute. A view taking `*args` or `**kwargs` accepts anything and is\nnever reported, nor is one reached through a decorator the type checker\ncannot see through. A class-based view is checked through the handler\nmethods it declares itself: what it inherits from django takes `**kwargs`.\n\n## Examples\n```python\npath(\"books/<int:pk>/\", views.detail, name=\"detail\")\n```\n\n```python\ndef detail(request, id): ...     # error: the route names `pk`\ndef detail(request): ...         # error: `pk` has nowhere to go\ndef detail(request, pk): ...     # ok\n```",
+          "default": "error",
+          "oneOf": [
+            {
+              "$ref": "#/definitions/Level"
+            }
+          ]
+        },
+        "invalid-route-parameter-type": {
+          "title": "detects a view declaring a type its route's converter does not produce",
+          "description": "## What it does\nChecks the type a view declares for a route argument against the type the\nroute's converter produces.\n\n## Why is this bad?\nA path converter parses the url before django calls the view:\n`<int:pk>` hands the view an `int` and `<uuid:key>` a `uuid.UUID`. A view\ndeclaring something else is annotated with a type its argument never has,\nso everything written against the annotation is written against a value\nthat is not there.\n\nUnlike `invalid-route-handler` this does not stop the request: django\ncalls the view and the wrong value arrives silently.\nAn unannotated parameter declares nothing and is never reported,\nand neither is one matched by a regular expression, which goes through no\nconverter at all.\n\n## Examples\n```python\npath(\"books/<int:pk>/\", views.detail, name=\"detail\")\n```\n\n```python\ndef detail(request, pk: str): ...    # warning: the converter gives an `int`\ndef detail(request, pk: int): ...    # ok\n```",
+          "default": "warn",
+          "oneOf": [
+            {
+              "$ref": "#/definitions/Level"
+            }
+          ]
+        },
         "invalid-super-argument": {
           "title": "detects invalid arguments for `super()`",
           "description": "## What it does\n\nDetects `super()` calls where:\n\n- the first argument is not a valid class literal, or\n- the second argument is not an instance or subclass of the first argument.\n\n## Why is this bad?\n\n`super(type, obj)` expects:\n\n- the first argument to be a class,\n- and the second argument to satisfy one of the following:\n    - `isinstance(obj, type)` is `True`\n    - `issubclass(obj, type)` is `True`\n\nViolating this relationship will raise a `TypeError` at runtime.\n\n## Examples\n\n```python\nclass A: ...\n\n\nclass B(A): ...\n\n\nsuper(A, B())  # it's okay! `A` satisfies `isinstance(B(), A)`\n\n# `A()` is not a class\nsuper(A(), B())  # error\n\n# `A()` does not satisfy `isinstance(A(), B)`\nsuper(B, A())  # error\n# `A` does not satisfy `issubclass(A, B)`\nsuper(B, A)  # error\n```\n\n## References\n\n- [Python documentation: super()](https://docs.python.org/3/library/functions.html#super)",

From af74194acf23d2b3d884091cac88167c75d76802 Mon Sep 17 00:00:00 2001
From: KotlinIsland <65446343+kotlinisland@users.noreply.github.com>
Date: Sat, 8 Aug 2026 21:38:32 +1000
Subject: [PATCH 08/16] a class-body field list resolves against its model
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

a model's `Meta.ordering`, a `ModelSerializer`'s and `ModelForm`'s `Meta.fields`
and `exclude` against `Meta.model`, and a drf view's `ordering_fields`,
`search_fields` and `filterset_fields` against the model its own queryset is of.
nothing is reported unless the model is certain

`source="author.name"` is deliberately not checked: drf resolves it with `getattr`
at serialization time against whatever object it is handed, so the canonical
`.annotate()` idiom names an attribute the model provably lacks

and `defaults`, with `create_defaults` on `update_or_create`, are django's own
keywords rather than lookups — four false positives on textbook django
---
 .../resources/mdtest/external/django.md       | 109 +++++++
 .../resources/mdtest/external/drf.lock        | 135 +++++++++
 .../resources/mdtest/external/drf.md          | 214 +++++++++++++
 .../src/types/dedicated/django.rs             | 281 +++++++++++++++++-
 .../src/types/infer/builder.rs                |  94 +++++-
 docs/basedpython/frameworks/django.md         |  12 +
 6 files changed, 841 insertions(+), 4 deletions(-)
 create mode 100644 crates/ty_python_semantic/resources/mdtest/external/drf.lock
 create mode 100644 crates/ty_python_semantic/resources/mdtest/external/drf.md

diff --git a/crates/ty_python_semantic/resources/mdtest/external/django.md b/crates/ty_python_semantic/resources/mdtest/external/django.md
index 106969fa59..bc3baeec35 100644
--- a/crates/ty_python_semantic/resources/mdtest/external/django.md
+++ b/crates/ty_python_semantic/resources/mdtest/external/django.md
@@ -277,6 +277,115 @@ Author.objects.order_by("bogus")
 Book.objects.filter(author__nonfield="x")
 ```
 
+## The `*_or_create` family's own keywords
+
+`defaults` and `create_defaults` carry the values to apply on create; they are django's own
+keywords, not lookups, so they name no field and are not resolved as one.
+
+```py
+from django.db import models
+
+class Author(models.Model):
+    name = models.CharField(max_length=100)
+    age = models.IntegerField()
+
+Author.objects.get_or_create(name="x", defaults={"age": 3})
+Author.objects.update_or_create(name="x", defaults={"age": 3})
+Author.objects.update_or_create(name="x", create_defaults={"age": 3}, defaults={})
+
+async def create_one() -> None:
+    await Author.objects.aget_or_create(name="x", defaults={"age": 3})
+
+# the lookup keys beside them are still checked
+# error: [invalid-field-lookup] "Model `Author` has no field `nam`"
+Author.objects.get_or_create(nam="x", defaults={"age": 3})
+
+# and `defaults` is not a keyword of the plain lookup methods
+# error: [invalid-field-lookup] "Model `Author` has no field `defaults`"
+Author.objects.filter(defaults={"age": 3})
+```
+
+## Model `Meta.ordering`
+
+`Meta.ordering` holds `order_by` syntax — a leading `-` and the `?` sentinel are both legal. Django
+resolves it at import time and reports a bad entry as `models.E015`; the stubs type it as plain
+`list[str]`, so ty resolves each literal entry against the model declaring the `Meta`.
+
+```py
+from django.db import models
+
+class Author(models.Model):
+    name = models.CharField(max_length=100)
+
+class Book(models.Model):
+    title = models.CharField(max_length=100)
+    published = models.DateField()
+    author = models.ForeignKey(Author, on_delete=models.CASCADE)
+
+    class Meta:
+        ordering = ["-published", "title", "pk", "?", "author__name", "author_id", "author"]
+
+class Bad(models.Model):
+    title = models.CharField(max_length=100)
+
+    class Meta:
+        ordering = [
+            "title",
+            # error: [invalid-field-lookup] "Model `Bad` has no field `nope` (in `ordering`)"
+            "nope",
+            # error: [invalid-field-lookup] "Model `Bad` has no field `alsonope` (in `ordering`)"
+            "-alsonope",
+        ]
+```
+
+## `Meta.ordering` refusals
+
+Nothing is reported when the list cannot be read exhaustively, when the `Meta` belongs to something
+that is not a model, or when `ordering` is written outside a `Meta`.
+
+```py
+from django.db import models
+
+NAMES = ["nope"]
+
+class Book(models.Model):
+    title = models.CharField(max_length=100)
+
+    class Meta:
+        # a name, not a literal list — its elements are unknown here
+        ordering = NAMES
+
+class Dynamic(models.Model):
+    title = models.CharField(max_length=100)
+
+    class Meta:
+        # one non-literal element makes the whole list unverifiable
+        ordering = ["nope", *NAMES]
+
+class Annotated(models.Model):
+    title = models.CharField(max_length=100)
+
+    class Meta:
+        # an annotation changes nothing about the entries
+        # error: [invalid-field-lookup] "Model `Annotated` has no field `nope` (in `ordering`)"
+        ordering: list[str] = ["title", "nope"]
+
+class NotAMeta(models.Model):
+    title = models.CharField(max_length=100)
+
+    class Config:
+        ordering = ["nope"]
+
+class Plain:
+    class Meta:
+        ordering = ["nope"]
+
+class AlsoNotChecked(models.Model):
+    title = models.CharField(max_length=100)
+    # `ordering` on the model itself is not django's `Meta.ordering`
+    ordering = ["nope"]
+```
+
 ## get_FOO_display for choice fields
 
 A field declared with `choices=` gets a synthesized `get_<field>_display()` method; a field without
diff --git a/crates/ty_python_semantic/resources/mdtest/external/drf.lock b/crates/ty_python_semantic/resources/mdtest/external/drf.lock
new file mode 100644
index 0000000000..e42baf0172
--- /dev/null
+++ b/crates/ty_python_semantic/resources/mdtest/external/drf.lock
@@ -0,0 +1,135 @@
+version = 1
+revision = 3
+requires-python = "==3.13.*"
+
+[[package]]
+name = "asgiref"
+version = "3.12.1"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/e6/26/3b59f2bdae5f640389becb1f673cded775287f5fc4f816309d9ca9a3f93d/asgiref-3.12.1.tar.gz", hash = "sha256:59dcb51c272ad209d59bed5708a64a333083e86017d7fcdd67498eeab7784340", size = 42378, upload-time = "2026-07-14T09:56:18.087Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/c0/1b/54f4ad77cd8a584fa70746c47df988e002cf1ee1eba43364d46f87803647/asgiref-3.12.1-py3-none-any.whl", hash = "sha256:fe386d1c2bff7259ea95929266d12a8cf9a8b5a1c2598402967d8792e7a7c094", size = 25478, upload-time = "2026-07-14T09:56:16.926Z" },
+]
+
+[[package]]
+name = "django"
+version = "6.0.7"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "asgiref" },
+    { name = "sqlparse" },
+    { name = "tzdata", marker = "sys_platform == 'win32'" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/89/55/664f24ff81c9ea19cb7dfc851afeae1f3c2390c7aee01d4ded68b5c1580d/django-6.0.7.tar.gz", hash = "sha256:2998503fc083124fb58037084bfa00de323c7c743f05f1b4284e77bff0ab8890", size = 10921299, upload-time = "2026-07-07T13:51:26.485Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/ba/ec/1ce5334b6a2c52ce619c23a0be8d366a57a0e080ebb2d88266e5c849157c/django-6.0.7-py3-none-any.whl", hash = "sha256:a037427c2288443a8c02a1b02295a31c239663aa682bc50b1976afb7cf6a769e", size = 8373344, upload-time = "2026-07-07T13:51:20.007Z" },
+]
+
+[[package]]
+name = "django-stubs"
+version = "6.0.7"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "django" },
+    { name = "django-stubs-ext" },
+    { name = "types-pyyaml" },
+    { name = "typing-extensions" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/8a/90/087c6e424e705e05182e543ef6b366a59eb5c92ab008b0dbbba55f357a40/django_stubs-6.0.7.tar.gz", hash = "sha256:bc55431c0af745a64e39cf33a8d36c87dccbedeae2fe26fab47dd355270e8538", size = 282293, upload-time = "2026-07-14T10:08:27.122Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/02/86/230ae6056221b543d63f7710d73967fe1c6840693540e99ea3c54f45859c/django_stubs-6.0.7-py3-none-any.whl", hash = "sha256:7ed9a14c438e589272ca04e966dee82a4d1ff7ca5c2171bc986c50a0d03ec35b", size = 547460, upload-time = "2026-07-14T10:08:25.626Z" },
+]
+
+[[package]]
+name = "django-stubs-ext"
+version = "6.0.8"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "django" },
+    { name = "typing-extensions" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/b2/54/79c06f12606ca1d22510900a251aeee92b9d91f80385d62c0c493d54f00e/django_stubs_ext-6.0.8.tar.gz", hash = "sha256:a64c332fc2f907b3bfeed38f1751eff1cbb377873c834d875b4cb0fdb63a3782", size = 6843, upload-time = "2026-08-06T11:04:30.701Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/e5/52/dd438b231490a6be853446b0bf32ec8a011ff4e386e7f8813659a2830664/django_stubs_ext-6.0.8-py3-none-any.whl", hash = "sha256:2214729fd9ebdc1c6ea4dde939db4c4b4b827473926dfe228f1588f7f637a9a2", size = 10401, upload-time = "2026-08-06T11:04:29.602Z" },
+]
+
+[[package]]
+name = "djangorestframework"
+version = "3.17.2"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "django" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/3b/35/c96055e700fdff25da3a7b7756cfd1d4dc54f38b9bc6d6c5e19e3a0fdc20/djangorestframework-3.17.2.tar.gz", hash = "sha256:89ed713b6dc83e1539f214b7d10808ae19bb8511004beba886225da6d5c9dafa", size = 906683, upload-time = "2026-08-05T07:47:22.5Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/a2/46/c14108e400b208c394325eb63fbae06c81341b6447fa1a6f9da718b17fe7/djangorestframework-3.17.2-py3-none-any.whl", hash = "sha256:cb0546a7415d5b46c04e0f4fe0a54b2109f4fdd5e83ca773c8c6183a6493d042", size = 899109, upload-time = "2026-08-05T07:47:20.853Z" },
+]
+
+[[package]]
+name = "djangorestframework-stubs"
+version = "3.17.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "django-stubs" },
+    { name = "types-pyyaml" },
+    { name = "typing-extensions" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/8a/4b/1bee065c6c87ee04b905732deb53acdfc43d0e5673f43a5f75ec4deb7f6f/djangorestframework_stubs-3.17.1.tar.gz", hash = "sha256:5b67655090e2976b778bad572840b732a87ab2911402530d0dca2fbf72f891c5", size = 33470, upload-time = "2026-07-28T21:27:52.071Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/86/38/6a04ffca56e24220bf37494fe9f75ce9abe8115776a90c924732bb37823a/djangorestframework_stubs-3.17.1-py3-none-any.whl", hash = "sha256:40f1f22ec1965d1caff17c66794b87799eb8f42e0628ea46b501dcd565d8a803", size = 57562, upload-time = "2026-07-28T21:27:50.58Z" },
+]
+
+[[package]]
+name = "mdtest-deps"
+version = "0.1.0"
+source = { virtual = "." }
+dependencies = [
+    { name = "django" },
+    { name = "django-stubs" },
+    { name = "djangorestframework" },
+    { name = "djangorestframework-stubs" },
+]
+
+[package.metadata]
+requires-dist = [
+    { name = "django", specifier = "==6.0.7" },
+    { name = "django-stubs", specifier = "==6.0.7" },
+    { name = "djangorestframework", specifier = "==3.17.2" },
+    { name = "djangorestframework-stubs", specifier = "==3.17.1" },
+]
+
+[[package]]
+name = "sqlparse"
+version = "0.5.5"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/90/76/437d71068094df0726366574cf3432a4ed754217b436eb7429415cf2d480/sqlparse-0.5.5.tar.gz", hash = "sha256:e20d4a9b0b8585fdf63b10d30066c7c94c5d7a7ec47c889a2d83a3caa93ff28e", size = 120815, upload-time = "2025-12-19T07:17:45.073Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/49/4b/359f28a903c13438ef59ebeee215fb25da53066db67b305c125f1c6d2a25/sqlparse-0.5.5-py3-none-any.whl", hash = "sha256:12a08b3bf3eec877c519589833aed092e2444e68240a3577e8e26148acc7b1ba", size = 46138, upload-time = "2025-12-19T07:17:46.573Z" },
+]
+
+[[package]]
+name = "types-pyyaml"
+version = "6.0.12.20260724"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/3f/6f/a28f44bcd56bebed42b028a2894c79853e2f5e6b5279e633cb3f287a05e7/types_pyyaml-6.0.12.20260724.tar.gz", hash = "sha256:3c1ce1bb73cd5ec02e90390c2b1f00e810d241d8825fd73ff359696839271b6b", size = 17893, upload-time = "2026-07-24T04:58:43.453Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/8b/42/0337fefc615e20ee55d1c8f71b774a9b2b734a04669139c20753b27a2a3a/types_pyyaml-6.0.12.20260724-py3-none-any.whl", hash = "sha256:d57db930a4b2efbc57cf430ec8882765d246929432fa253092f383902329a453", size = 20312, upload-time = "2026-07-24T04:58:42.486Z" },
+]
+
+[[package]]
+name = "typing-extensions"
+version = "4.16.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/f6/cc/6253133b5bb138fc3306cebfbda2c520f545d36b5be2c7255cc528bb45d6/typing_extensions-4.16.0.tar.gz", hash = "sha256:dc983d19a509c94dba722ee6abd33940f7c05a89e243c47e907eb4db6f1a43e5", size = 113555, upload-time = "2026-07-02T08:40:05.92Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/49/d3/b8441a820a491ddfc024b0b0cf0393375b75ea13866d9c66727e54c2fc80/typing_extensions-4.16.0-py3-none-any.whl", hash = "sha256:481caa481374e813c1b176ada14e97f1f67a4539ce9cfeb3f350d78d6370c2e8", size = 45571, upload-time = "2026-07-02T08:40:04.659Z" },
+]
+
+[[package]]
+name = "tzdata"
+version = "2026.3"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/92/ff/5a28bdfd8c3ebec42564ac7d0e54ca3db65044a9314a97f9564fa7a1e926/tzdata-2026.3.tar.gz", hash = "sha256:4a1518b8993086a7982523e071643f3c0e5f213e75b21318e78bcabfff9d1415", size = 198674, upload-time = "2026-07-10T08:50:37.887Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/e5/6d/b53b99a9f2766d095985947a5782f1702cabb129a34f7a802d7197af832f/tzdata-2026.3-py2.py3-none-any.whl", hash = "sha256:dc096730c87af6cab1b171c9d532be840741ff5d459015e7f6947bd7d7e54931", size = 348168, upload-time = "2026-07-10T08:50:36.46Z" },
+]
diff --git a/crates/ty_python_semantic/resources/mdtest/external/drf.md b/crates/ty_python_semantic/resources/mdtest/external/drf.md
new file mode 100644
index 0000000000..ab60b594fa
--- /dev/null
+++ b/crates/ty_python_semantic/resources/mdtest/external/drf.md
@@ -0,0 +1,214 @@
+# Django REST framework
+
+Types come from the `djangorestframework-stubs` package. drf declares model field paths as
+class-body lists of plain strings, so a typo survives the stubs and only fails at runtime — when the
+serializer is first built, or when a request asks for that ordering / search / filter. ty resolves
+each literal entry against the model the declaring class names.
+
+```toml
+[environment]
+python-version = "3.13"
+python-platform = "linux"
+
+[project]
+dependencies = [
+    "django==6.0.7",
+    "django-stubs==6.0.7",
+    "djangorestframework==3.17.2",
+    "djangorestframework-stubs==3.17.1",
+]
+```
+
+## Serializer `Meta.fields`
+
+Every entry must name something reachable on `Meta.model` — drf builds a read-only property field
+for a non-field attribute, so a method, a property, the `pk` alias and an `<fk>_id` attname are all
+as valid as a field — or a field the serializer itself declares. `fields = "__all__"` is a sentinel.
+
+```py
+from django.db import models
+from rest_framework import serializers
+
+class Author(models.Model):
+    name = models.CharField(max_length=100)
+
+class Book(models.Model):
+    title = models.CharField(max_length=100)
+    author = models.ForeignKey(Author, on_delete=models.CASCADE)
+
+    def get_absolute_url(self) -> str:
+        return ""
+
+class Everything(serializers.ModelSerializer[Book]):
+    declared = serializers.CharField(source="title")
+
+    class Meta:
+        model = Book
+        # a field, a relation, the pk alias, an attname, a model method, a declared field
+        fields = ["title", "author", "pk", "id", "author_id", "get_absolute_url", "declared"]
+
+class AllFields(serializers.ModelSerializer[Book]):
+    class Meta:
+        model = Book
+        fields = "__all__"
+
+class Reverse(serializers.ModelSerializer[Author]):
+    class Meta:
+        model = Author
+        # the reverse accessor django synthesizes for `Book.author`
+        fields = ["id", "name", "book_set"]
+
+class Typo(serializers.ModelSerializer[Book]):
+    class Meta:
+        model = Book
+        fields = [
+            "title",
+            # error: [invalid-field-lookup] "Model `Book` has no field `titel` (in `fields`)"
+            "titel",
+        ]
+```
+
+## Serializer `Meta.exclude`
+
+`exclude` is resolved the same way; drf asserts on an entry that matches no model field.
+
+```py
+from django.db import models
+from rest_framework import serializers
+
+class Book(models.Model):
+    title = models.CharField(max_length=100)
+    published = models.DateField()
+
+class Fine(serializers.ModelSerializer[Book]):
+    class Meta:
+        model = Book
+        exclude = ["published"]
+
+class Typo(serializers.ModelSerializer[Book]):
+    class Meta:
+        model = Book
+        # error: [invalid-field-lookup] "Model `Book` has no field `publshed` (in `exclude`)"
+        exclude = ["publshed"]
+```
+
+## Serializer refusals
+
+Nothing is reported when the model is not certain: no `Meta.model`, a `Meta.model` that is not a
+model, or a list that cannot be read exhaustively.
+
+```py
+from django.db import models
+from rest_framework import serializers
+
+class Book(models.Model):
+    title = models.CharField(max_length=100)
+
+class NotAModel: ...
+
+EXTRA = ["nope"]
+
+class NoModel(serializers.ModelSerializer[Book]):
+    class Meta:
+        fields = ["nope"]
+
+class WrongModel(serializers.ModelSerializer[Book]):
+    class Meta:
+        model = NotAModel
+        fields = ["nope"]
+
+class Dynamic(serializers.ModelSerializer[Book]):
+    class Meta:
+        model = Book
+        fields = ["nope", *EXTRA]
+
+class FromAName(serializers.ModelSerializer[Book]):
+    class Meta:
+        model = Book
+        fields = EXTRA
+
+class PlainSerializer(serializers.Serializer[Book]):
+    class Meta:
+        model = Book
+        fields = ["nope"]
+```
+
+## View filter-backend field lists
+
+`ordering_fields`, `filterset_fields` and `search_fields` are resolved against the model the view's
+own `queryset` is a queryset of. `search_fields` entries may carry one of `SearchFilter`'s lookup
+prefixes (`^`, `=`, `@`, `$`), and `"__all__"` is a sentinel.
+
+```py
+from django.db import models
+from rest_framework import generics
+
+class Author(models.Model):
+    name = models.CharField(max_length=100)
+
+class Book(models.Model):
+    title = models.CharField(max_length=100)
+    published = models.DateField()
+    author = models.ForeignKey(Author, on_delete=models.CASCADE)
+
+class Good(generics.ListAPIView[Book]):
+    queryset = Book.objects.all()
+    ordering_fields = ["published", "author__name"]
+    search_fields = ["title", "^title", "=title", "$title", "author__name"]
+    filterset_fields = ["title", "author"]
+
+class AllOrdering(generics.ListAPIView[Book]):
+    queryset = Book.objects.all()
+    ordering_fields = "__all__"
+
+class DictFilterset(generics.ListAPIView[Book]):
+    queryset = Book.objects.all()
+    filterset_fields = {"title": ["exact", "contains"]}
+
+class Typos(generics.ListAPIView[Book]):
+    queryset = Book.objects.all()
+    # error: [invalid-field-lookup] "Model `Book` has no field `publishd` (in `ordering_fields`)"
+    ordering_fields = ["publishd"]
+    # error: [invalid-field-lookup] "Model `Book` has no field `titel` (in `search_fields`)"
+    search_fields = ["^titel"]
+    # error: [invalid-field-lookup] "Model `Book` has no field `nope` (in `filterset_fields`)"
+    filterset_fields = {"nope": ["exact"]}
+
+class TypoAcrossRelation(generics.ListAPIView[Book]):
+    queryset = Book.objects.all()
+    # error: [invalid-field-lookup] "Model `Author` has no field `nome` (in `ordering_fields`)"
+    ordering_fields = ["author__nome"]
+
+class Annotated(generics.ListAPIView[Book]):
+    queryset = Book.objects.all()
+    ordering_fields: list[str] = ["published"]
+    # error: [invalid-field-lookup] "Model `Book` has no field `publishd` (in `search_fields`)"
+    search_fields: list[str] = ["publishd"]
+```
+
+## View refusals
+
+A view whose queryset cannot be traced to a model names nothing to resolve against. drf removed the
+`model` attribute in 3.0, so that is not a source either.
+
+```py
+from django.db import models
+from rest_framework import generics
+
+class Book(models.Model):
+    title = models.CharField(max_length=100)
+
+class FromMethod(generics.ListAPIView[Book]):
+    ordering_fields = ["nope"]
+
+    def get_queryset(self):
+        return Book.objects.all()
+
+class LegacyModelAttribute(generics.ListAPIView[Book]):
+    model = Book
+    ordering_fields = ["nope"]
+
+class NotAView:
+    queryset = Book.objects.all()
+    ordering_fields = ["nope"]
+```
diff --git a/crates/ty_python_semantic/src/types/dedicated/django.rs b/crates/ty_python_semantic/src/types/dedicated/django.rs
index 97e45c5fc2..3c8d22a314 100644
--- a/crates/ty_python_semantic/src/types/dedicated/django.rs
+++ b/crates/ty_python_semantic/src/types/dedicated/django.rs
@@ -12,12 +12,14 @@
 use std::borrow::Cow;
 
 use ruff_db::parsed::ParsedModuleRef;
+use ruff_python_ast as ast;
 use ruff_python_ast::name::Name;
-use ty_module_resolver::KnownModule;
+use ruff_text_size::TextRange;
+use ty_module_resolver::{KnownModule, file_to_module};
 use ty_python_core::definition::{Definition, DefinitionKind, DefinitionState};
-use ty_python_core::{global_scope, use_def_map};
+use ty_python_core::{global_scope, place_table, use_def_map};
 
-use crate::place::known_module_symbol;
+use crate::place::{Place, known_module_symbol};
 use crate::types::class::{CodeGeneratorKind, Field, FieldKind};
 use crate::types::member::class_member;
 use crate::types::signatures::{Parameter, Parameters, Signature};
@@ -56,6 +58,63 @@ fn has_base(db: &dyn Db, class: StaticClassLiteral<'_>, base: KnownClass) -> boo
         .any(|candidate| candidate.is_known(db, base))
 }
 
+/// `class` has a base declared as `name` in the module `module`
+///
+/// the classes this identifies (drf's view and serializer bases, django's
+/// `ModelForm`) carry no runtime magic of their own, so they earn no
+/// `KnownClass` variant; matching the declaring module and name keeps the
+/// recognition just as exact
+fn has_base_named(db: &dyn Db, class: StaticClassLiteral<'_>, module: &str, name: &str) -> bool {
+    class
+        .iter_mro(db, None)
+        .filter_map(ClassBase::into_class)
+        .filter_map(|candidate| candidate.class_literal(db).as_static())
+        .any(|candidate| {
+            candidate.name(db) == name
+                && file_to_module(db, candidate.file(db))
+                    .is_some_and(|candidate_module| candidate_module.name(db) == module)
+        })
+}
+
+/// `class` is a drf view or viewset — the classes whose `queryset` names the
+/// model their filter-backend field lists are resolved against
+fn is_drf_generic_view(db: &dyn Db, class: StaticClassLiteral<'_>) -> bool {
+    has_base_named(db, class, "rest_framework.generics", "GenericAPIView")
+}
+
+/// the model a drf view's filter-backend field lists resolve against: the
+/// model its own `queryset` is a queryset of. `None` for anything else —
+/// a view that builds its queryset in `get_queryset`, or inherits it, leaves
+/// nothing to resolve against, and drf ignores the `model` attribute entirely
+/// (it was removed in drf 3.0), so that is not a source either
+#[salsa::tracked(returns(copy), heap_size=ruff_memory_usage::heap_size)]
+pub(in crate::types) fn drf_view_model<'db>(
+    db: &'db dyn Db,
+    class: StaticClassLiteral<'db>,
+) -> Option<StaticClassLiteral<'db>> {
+    if !is_drf_generic_view(db, class) {
+        return None;
+    }
+    // read the sibling `queryset` binding straight out of the class body:
+    // resolving it as a member would infer the very scope this runs from
+    let body_scope = class.body_scope(db);
+    let symbol = place_table(db, body_scope).symbol_id("queryset")?;
+    let use_def = use_def_map(db, body_scope);
+    let mut model = None;
+    for binding in use_def.end_of_scope_symbol_bindings(symbol) {
+        let DefinitionState::Defined(definition) = binding.binding else {
+            continue;
+        };
+        let candidate = queryset_or_manager_model(db, binding_type(db, definition))?;
+        // more than one binding only agrees if they name the same model
+        if model.is_some_and(|model| model != candidate) {
+            return None;
+        }
+        model = Some(candidate);
+    }
+    model
+}
+
 /// the specialized instance type constructed by a django field constructor
 /// call, or `None` when the call is not one or its facts don't resolve
 ///
@@ -690,6 +749,18 @@ pub(in crate::types) fn queryset_method_kind(name: &str) -> Option<QuerysetMetho
     }
 }
 
+/// whether `key` is a keyword the method `method` declares itself, rather than
+/// a field lookup. the `*_or_create` family carries the values to apply on
+/// create in `defaults` (and, since django 5.0, `create_defaults` on
+/// `update_or_create`), so those names are django's own
+pub(in crate::types) fn is_method_own_keyword(method: &str, key: &str) -> bool {
+    match method {
+        "get_or_create" | "aget_or_create" => key == "defaults",
+        "update_or_create" | "aupdate_or_create" => key == "defaults" || key == "create_defaults",
+        _ => false,
+    }
+}
+
 /// the outcome of resolving one lookup / field-name key against a model
 pub(in crate::types) enum FieldResolution<'db> {
     /// the leading segment names no field of `model`
@@ -905,6 +976,210 @@ pub(in crate::types) fn resolve_field_name<'db>(
     }
 }
 
+// ---------------------------------------------------------------------------
+// class-body field-name lists
+//
+// several django / drf constructs declare model field paths as a class-body
+// list of strings rather than as call arguments. each is validated against a
+// model the declaring class names, and each has its own spelling rules. the
+// model source differs per site, so the builder resolves it and calls back
+// into `field_list_kind` for the per-entry spelling
+// ---------------------------------------------------------------------------
+
+/// the kind of `Meta.fields` / `Meta.exclude` declarer a class is
+#[derive(Clone, Copy, PartialEq, Eq)]
+pub(in crate::types) enum MetaFieldsDeclarer {
+    /// a drf `ModelSerializer`. every entry must name something reachable on
+    /// the model — a field, but equally a property, a method or a reverse
+    /// accessor, since drf falls back to a read-only property field — or a
+    /// field the serializer itself declares
+    ModelSerializer,
+    /// a django `ModelForm`. `fields` is stricter than drf (only editable
+    /// concrete fields), so the drf rule under-reports here rather than
+    /// risking a false positive. `exclude` is not checkable at all: django
+    /// silently ignores an entry that names nothing
+    ModelForm,
+}
+
+pub(in crate::types) fn meta_fields_declarer(
+    db: &dyn Db,
+    class: StaticClassLiteral<'_>,
+) -> Option<MetaFieldsDeclarer> {
+    if has_base_named(db, class, "rest_framework.serializers", "ModelSerializer") {
+        Some(MetaFieldsDeclarer::ModelSerializer)
+    } else if has_base_named(db, class, "django.forms.models", "ModelForm") {
+        Some(MetaFieldsDeclarer::ModelForm)
+    } else {
+        None
+    }
+}
+
+impl MetaFieldsDeclarer {
+    /// whether an entry of the class-body attribute `name` is worth resolving
+    pub(in crate::types) fn checks(self, name: &str) -> bool {
+        match self {
+            Self::ModelSerializer => name == "fields" || name == "exclude",
+            // django drops an unknown `exclude` entry without complaint
+            Self::ModelForm => name == "fields",
+        }
+    }
+}
+
+/// whether `name` is something a `Meta.fields` entry may legally name: an
+/// attribute of the model (drf builds a read-only property field for a
+/// non-field attribute, so a method or property is as valid as a field), or a
+/// field the declaring serializer / form declares itself
+///
+/// the declared-field side is read out of the place tables rather than by
+/// member lookup: the declaring class's body is the scope this runs from
+pub(in crate::types) fn is_meta_fields_entry_valid<'db>(
+    db: &'db dyn Db,
+    model: StaticClassLiteral<'db>,
+    declarer: StaticClassLiteral<'db>,
+    name: &str,
+) -> bool {
+    let model_instance = Type::instance(db, model.default_specialization(db));
+    if !matches!(model_instance.member(db, name).place, Place::Undefined) {
+        return true;
+    }
+    declarer
+        .iter_mro(db, None)
+        .filter_map(ClassBase::into_class)
+        .filter_map(|base| base.class_literal(db).as_static())
+        .any(|base| {
+            place_table(db, base.body_scope(db))
+                .symbol_id(name)
+                .is_some()
+        })
+}
+
+/// the model a nested `Meta` names, read from its own `model = <Model>`
+/// binding. `None` when there is none, or it doesn't resolve to a model
+pub(in crate::types) fn meta_model<'db>(
+    db: &'db dyn Db,
+    meta: StaticClassLiteral<'db>,
+) -> Option<StaticClassLiteral<'db>> {
+    let body_scope = meta.body_scope(db);
+    let symbol = place_table(db, body_scope).symbol_id("model")?;
+    let use_def = use_def_map(db, body_scope);
+    let mut model = None;
+    for binding in use_def.end_of_scope_symbol_bindings(symbol) {
+        let DefinitionState::Defined(definition) = binding.binding else {
+            continue;
+        };
+        let candidate = binding_type(db, definition)
+            .as_class_literal()
+            .and_then(ClassLiteral::as_static)
+            .filter(|candidate| is_model(db, *candidate))?;
+        if model.is_some_and(|model| model != candidate) {
+            return None;
+        }
+        model = Some(candidate);
+    }
+    model
+}
+
+/// a class-body attribute whose value is a list of model field paths
+#[derive(Clone, Copy, PartialEq, Eq)]
+pub(in crate::types) enum FieldListKind<'db> {
+    /// a model's `Meta.ordering`: `order_by` syntax, so a leading `-` and the
+    /// `?` sentinel are both legal. django reports a bad entry itself, as
+    /// `models.E015`
+    Ordering,
+    /// a drf view's `ordering_fields` / `filterset_fields`: plain field paths.
+    /// the whole attribute may instead be the `"__all__"` sentinel
+    ViewFieldNames,
+    /// a drf view's `search_fields`: a field path optionally carrying one of
+    /// `SearchFilter`'s lookup prefixes
+    SearchFieldNames,
+    /// a serializer's / form's `Meta.fields` or `Meta.exclude`: a plain name,
+    /// resolved against the model's attributes and `declaring`'s own fields
+    MetaFields { declaring: StaticClassLiteral<'db> },
+}
+
+/// the field-list site a class-body attribute named `name` declares, for a
+/// class that has already been established as the right kind of declarer
+pub(in crate::types) fn view_field_list_kind<'db>(name: &str) -> Option<FieldListKind<'db>> {
+    match name {
+        "ordering_fields" | "filterset_fields" => Some(FieldListKind::ViewFieldNames),
+        "search_fields" => Some(FieldListKind::SearchFieldNames),
+        _ => None,
+    }
+}
+
+/// the literal string entries of a class-body field-name list, with their
+/// ranges. `None` when the value is not a list this can read exhaustively —
+/// a comprehension, a name, a concatenation, or a list holding any
+/// non-literal element — because a partially-read list can't distinguish a
+/// typo from an entry supplied elsewhere
+pub(in crate::types) fn literal_field_list_entries(
+    value: &ast::Expr,
+) -> Option<Vec<(&str, TextRange)>> {
+    let elements = match value {
+        // `fields = "__all__"` and drf's `ordering_fields = "__all__"`: a bare
+        // string is a sentinel, never a field name
+        ast::Expr::StringLiteral(_) => return Some(Vec::new()),
+        ast::Expr::List(list) => &list.elts,
+        ast::Expr::Tuple(tuple) => &tuple.elts,
+        // `filterset_fields = {"title": ["exact"]}` maps a field path to the
+        // lookups allowed on it — the keys are the field paths
+        ast::Expr::Dict(dict) => {
+            return dict
+                .items
+                .iter()
+                .map(|item| {
+                    let literal = item.key.as_ref()?.as_string_literal_expr()?;
+                    Some((literal.value.to_str(), literal.range))
+                })
+                .collect();
+        }
+        _ => return None,
+    };
+    elements
+        .iter()
+        .map(|element| {
+            let literal = element.as_string_literal_expr()?;
+            Some((literal.value.to_str(), literal.range))
+        })
+        .collect()
+}
+
+impl<'db> FieldListKind<'db> {
+    /// resolve one literal entry of the list against `model`
+    pub(in crate::types) fn resolve(
+        self,
+        db: &'db dyn Db,
+        model: StaticClassLiteral<'db>,
+        entry: &str,
+    ) -> FieldResolution<'db> {
+        match self {
+            // `order_by` syntax — `-` and `?` included
+            Self::Ordering => resolve_field_name(db, model, entry),
+            Self::ViewFieldNames => resolve_lookup(db, model, entry),
+            Self::MetaFields { declaring } => {
+                if is_meta_fields_entry_valid(db, model, declaring, entry) {
+                    FieldResolution::Resolved { operand: None }
+                } else {
+                    FieldResolution::Unknown {
+                        model: model.name(db).as_str().into(),
+                        segment: entry.into(),
+                    }
+                }
+            }
+            Self::SearchFieldNames => {
+                // `SearchFilter` reads a leading `^` (istartswith), `=`
+                // (iexact), `@` (full-text search) or `$` (iregex) off the
+                // entry before using the rest as a field path
+                let path = entry.strip_prefix(['^', '=', '@', '$']).unwrap_or(entry);
+                if path.is_empty() {
+                    return FieldResolution::Resolved { operand: None };
+                }
+                resolve_lookup(db, model, path)
+            }
+        }
+    }
+}
+
 /// the read type of a `field__path` for a `values()`/`values_list()` row: the
 /// terminal field's `_GT` (a bare relation reads as the target pk). `None`
 /// when the path can't be statically resolved (so refinement is skipped)
diff --git a/crates/ty_python_semantic/src/types/infer/builder.rs b/crates/ty_python_semantic/src/types/infer/builder.rs
index ea97df3251..318ce019a9 100644
--- a/crates/ty_python_semantic/src/types/infer/builder.rs
+++ b/crates/ty_python_semantic/src/types/infer/builder.rs
@@ -57,7 +57,7 @@ use crate::types::callable::{CallableFunctionProvenance, CallableTypeKind};
 use crate::types::class::{
     ClassLiteral, CodeGeneratorKind, DynamicNamedTupleAnchor, DynamicNamedTupleLiteral,
     DynamicTypedDictAnchor, DynamicTypedDictLiteral, MethodDecorator, NamedTupleField,
-    NamedTupleSpec,
+    NamedTupleSpec, StaticClassLiteral,
 };
 use crate::types::constraints::{ConstraintSetBuilder, PathBounds, Solutions};
 use crate::types::context::InferContext;
@@ -3746,6 +3746,7 @@ impl<'db, 'ast> TypeInferenceBuilder<'db, 'ast> {
         self.store_expression_type(target, target_ty);
         add.insert(self, target_ty);
         self.check_unannotated_model_field(target, assignment.value(self.module()));
+        self.check_django_field_name_list(target, assignment.value(self.module()));
     }
 
     /// Pydantic requires every field to be annotated. An unannotated class-body
@@ -3793,6 +3794,89 @@ impl<'db, 'ast> TypeInferenceBuilder<'db, 'ast> {
         }
     }
 
+    /// The class whose body `scope` is, or `None` when `scope` is not a class body.
+    fn class_of_body_scope(&self, scope: FileScopeId) -> Option<StaticClassLiteral<'db>> {
+        let class_node = self.index.scope(scope).node().as_class()?;
+        let definition = self.index.expect_single_definition(class_node);
+        original_class_type(self.db(), definition)?.as_static()
+    }
+
+    /// The class lexically enclosing the class whose body `scope` is — for a
+    /// nested `Meta`, the model / serializer / form that declares it. A generic
+    /// outer class interposes its type-parameter scope, so skip that hop.
+    fn class_enclosing_body_scope(&self, scope: FileScopeId) -> Option<StaticClassLiteral<'db>> {
+        let mut parent = self.index.parent_scope_id(scope)?;
+        if self.index.scope(parent).kind() == ScopeKind::TypeParams {
+            parent = self.index.parent_scope_id(parent)?;
+        }
+        self.class_of_body_scope(parent)
+    }
+
+    /// Validate a class-body assignment of a list of django model field paths:
+    /// a model's `Meta.ordering`, and a drf view's `ordering_fields`,
+    /// `filterset_fields` and `search_fields`.
+    ///
+    /// Every one of these is a list of strings the stubs type as plain `str`,
+    /// so a typo is invisible until django resolves it — at import time for
+    /// `Meta.ordering` (`models.E015`), and only once a request asks for that
+    /// ordering / search / filter for the view attributes.
+    ///
+    /// Reporting requires the model to be resolved for certain. A class body
+    /// that names no model, a `queryset` that doesn't trace to one, and a
+    /// non-literal element are all left alone rather than guessed at.
+    fn check_django_field_name_list(&mut self, target: &ast::Expr, value: &ast::Expr) {
+        let ast::Expr::Name(name) = target else {
+            return;
+        };
+        let db = self.db();
+        let scope = self.scope().file_scope_id(db);
+        let name = name.id.as_str();
+
+        // `fields` / `exclude` / `ordering` all sit in a nested `Meta`; the
+        // drf view attributes sit in the view's own body
+        let meta = self
+            .class_of_body_scope(scope)
+            .filter(|meta| meta.name(db) == "Meta");
+        let declaring = meta.and_then(|_| self.class_enclosing_body_scope(scope));
+
+        let resolved = if name == "ordering" {
+            // a model's `Meta.ordering`: the model is the class declaring `Meta`
+            declaring
+                .filter(|model| django::is_model(db, *model))
+                .map(|model| (model, django::FieldListKind::Ordering))
+        } else if let Some((meta, declaring)) = meta.zip(declaring)
+            && let Some(declarer) = django::meta_fields_declarer(db, declaring)
+            && declarer.checks(name)
+        {
+            // a serializer's / form's `Meta.fields`: the model is `Meta.model`
+            django::meta_model(db, meta)
+                .map(|model| (model, django::FieldListKind::MetaFields { declaring }))
+        } else {
+            django::view_field_list_kind(name).and_then(|kind| {
+                let view = self.class_of_body_scope(scope)?;
+                Some((django::drf_view_model(db, view)?, kind))
+            })
+        };
+        let Some((model, kind)) = resolved else {
+            return;
+        };
+
+        // a list this can't read exhaustively is left alone entirely
+        let Some(entries) = django::literal_field_list_entries(value) else {
+            return;
+        };
+        for (entry, range) in entries {
+            if let django::FieldResolution::Unknown { model, segment } =
+                kind.resolve(db, model, entry)
+                && let Some(builder) = self.context.report_lint(&INVALID_FIELD_LOOKUP, range)
+            {
+                builder.into_diagnostic(format_args!(
+                    "Model `{model}` has no field `{segment}` (in `{name}`)"
+                ));
+            }
+        }
+    }
+
     fn stub_placeholder_binding_type(&self, value: &ast::Expr) -> Option<Type<'db>> {
         if self.in_stub() && value.is_ellipsis_literal_expr() {
             Some(Type::unknown())
@@ -4416,6 +4500,11 @@ impl<'db, 'ast> TypeInferenceBuilder<'db, 'ast> {
     }
 
     fn infer_annotated_assignment_statement(&mut self, assignment: &ast::StmtAnnAssign) {
+        // an annotation changes nothing about what the entries mean
+        // (`search_fields: list[str] = [...]`), so check the same sites here
+        if let Some(value) = &assignment.value {
+            self.check_django_field_name_list(&assignment.target, value);
+        }
         if assignment.target.is_name_expr() {
             self.infer_definition(assignment);
         } else {
@@ -10206,6 +10295,9 @@ impl<'db, 'ast> TypeInferenceBuilder<'db, 'ast> {
                         continue; // `**kwargs` unpacking — can't check statically
                     };
                     let key = arg.as_str();
+                    if django::is_method_own_keyword(method_name.as_str(), key) {
+                        continue;
+                    }
                     let resolution = if is_create {
                         django::resolve_create_kwarg(db, model, key)
                     } else {
diff --git a/docs/basedpython/frameworks/django.md b/docs/basedpython/frameworks/django.md
index 9e359ac105..d74b4c32ec 100644
--- a/docs/basedpython/frameworks/django.md
+++ b/docs/basedpython/frameworks/django.md
@@ -25,6 +25,18 @@ basedpython supports django models. the type checker understands django's unanno
 - lookup kwargs are validated: `filter(name__startswith="x")` checks that `name` is a field and `startswith` is a valid lookup for strings
 - relation traversal in lookups: `filter(author__birthday__lt=date(2000, 1, 1))` follows foreign keys and checks field types
 
+### class-body field-name lists
+
+several django and drf constructs spell model field paths as a class-body list of plain strings, which the stubs type as `list[str]`. each literal entry is resolved against the model the declaring class names:
+
+- a model's `Meta.ordering` — `order_by` syntax, so a leading `-` and `?` are legal. django reports a bad entry itself, as `models.E015`
+- a drf `ModelSerializer`'s / a `ModelForm`'s `Meta.fields` and `Meta.exclude`, against `Meta.model`. drf builds a read-only property field for a non-field attribute, so a model method, a property, `pk` and an `<fk>_id` attname are all legal, as is a field the serializer declares itself. `"__all__"` is a sentinel
+- a drf view's `ordering_fields`, `search_fields` and `filterset_fields`, against the model its own `queryset` is a queryset of. a `search_fields` entry may carry one of `SearchFilter`'s `^`, `=`, `@`, `$` prefixes
+
+nothing is reported unless the model is certain. a serializer without a `Meta.model`, a view that builds its queryset in `get_queryset`, and a list holding any non-literal element are all left alone
+
+`source="author.name"` on a serializer field is deliberately **not** checked: drf resolves it with `getattr` at serialization time against whatever object it is handed, which is routinely an annotated row or a dict rather than an instance of `Meta.model`
+
 ### transpilation compatibility
 
 - `optional?.chaining` works across nullable relations: `author?.birthday?.year`

From 40e56653b9ae182475b3e6be672daf2d205de378 Mon Sep 17 00:00:00 2001
From: KotlinIsland <65446343+kotlinisland@users.noreply.github.com>
Date: Sat, 8 Aug 2026 21:38:32 +1000
Subject: [PATCH 09/16] django will not call a template member that alters data
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

django's own set, gated three ways: the receiver is a class django marks, a
`django.*` class in the mro declares the name, and the member is a method rather
than a value. the gate is what makes it more than a table — a model's own
`update()` is not flagged while an *override* of `save` is, and django agrees with
both

212 members compared against django's own three-arm resolution: 40 refused, 40
flagged, no false positives and no misses. completion marks the five and sorts
them last, which is the direct answer to a template author seeing `save` first
---
 _typos.toml                                   |   1 +
 crates/ty/docs/rules.md                       |  63 +++++--
 crates/ty_ide/src/django_template.rs          |   9 +
 .../ty_ide/src/django_template/completion.rs  | 166 +++++++++++++++++-
 .../ty_ide/src/django_template/diagnostics.rs | 144 +++++++++++++--
 crates/ty_ide/src/django_template/resolve.rs  |  15 +-
 .../ty_python_semantic/src/django_template.rs |  30 ++++
 .../src/types/dedicated/django.rs             | 120 +++++++++++++
 .../src/types/ide_support.rs                  |  57 ++++++
 .../src/server/api/requests/completion.rs     |   6 +
 .../frameworks/django-templates.md            |  15 +-
 ty.schema.json                                |  10 ++
 12 files changed, 606 insertions(+), 30 deletions(-)

diff --git a/_typos.toml b/_typos.toml
index d9a85a6d8b..ec2875012d 100644
--- a/_typos.toml
+++ b/_typos.toml
@@ -25,6 +25,7 @@ BA = "BA" # acronym for "Bad Allowed", used in testing.
 jod = "jod" # e.g., `jod-thread`
 Numer = "Numer" # Library name 'NumerBlox' in "Who's Using Ruff?"
 CPY = "CPY"  # it's a Ruff rule category
+aadd = "aadd"  # django's async `add`, alongside `acreate`, `aset` and the rest
 
 [default]
 extend-ignore-re = [
diff --git a/crates/ty/docs/rules.md b/crates/ty/docs/rules.md
index b195b2a79a..dd561e8def 100644
--- a/crates/ty/docs/rules.md
+++ b/crates/ty/docs/rules.md
@@ -3426,7 +3426,7 @@ def func() -> int:
 Default level: <a href="../../rules#rule-levels" title="This lint has a default level of 'error'."><code>error</code></a> ·
 Added in <a href="https://github.com/astral-sh/ty/releases/tag/0.0.69">0.0.69</a> ·
 <a href="https://github.com/astral-sh/ty/issues?q=sort%3Aupdated-desc%20is%3Aissue%20is%3Aopen%20%22invalid-route-arguments%22" target="_blank">Related issues</a> ·
-<a href="https://github.com/astral-sh/ruff/blob/main/crates%2Fty_python_semantic%2Fsrc%2Fdjango_template.rs#L241" target="_blank">View source</a>
+<a href="https://github.com/astral-sh/ruff/blob/main/crates%2Fty_python_semantic%2Fsrc%2Fdjango_template.rs#L242" target="_blank">View source</a>
 </small>
 
 
@@ -3459,7 +3459,7 @@ routes share is reported only when none of them accepts the arguments.
 Default level: <a href="../../rules#rule-levels" title="This lint has a default level of 'error'."><code>error</code></a> ·
 Added in <a href="https://github.com/astral-sh/ty/releases/tag/0.0.69">0.0.69</a> ·
 <a href="https://github.com/astral-sh/ty/issues?q=sort%3Aupdated-desc%20is%3Aissue%20is%3Aopen%20%22invalid-route-handler%22" target="_blank">Related issues</a> ·
-<a href="https://github.com/astral-sh/ruff/blob/main/crates%2Fty_python_semantic%2Fsrc%2Fdjango_template.rs#L323" target="_blank">View source</a>
+<a href="https://github.com/astral-sh/ruff/blob/main/crates%2Fty_python_semantic%2Fsrc%2Fdjango_template.rs#L353" target="_blank">View source</a>
 </small>
 
 
@@ -3500,7 +3500,7 @@ def detail(request, pk): ...     # ok
 Default level: <a href="../../rules#rule-levels" title="This lint has a default level of 'warn'."><code>warn</code></a> ·
 Added in <a href="https://github.com/astral-sh/ty/releases/tag/0.0.69">0.0.69</a> ·
 <a href="https://github.com/astral-sh/ty/issues?q=sort%3Aupdated-desc%20is%3Aissue%20is%3Aopen%20%22invalid-route-parameter-type%22" target="_blank">Related issues</a> ·
-<a href="https://github.com/astral-sh/ruff/blob/main/crates%2Fty_python_semantic%2Fsrc%2Fdjango_template.rs#L358" target="_blank">View source</a>
+<a href="https://github.com/astral-sh/ruff/blob/main/crates%2Fty_python_semantic%2Fsrc%2Fdjango_template.rs#L388" target="_blank">View source</a>
 </small>
 
 
@@ -6124,13 +6124,48 @@ class F(NamedTuple):
 
 - [Python documentation: super()](https://docs.python.org/3/library/functions.html#super)
 
+## `template-member-alters-data`
+
+<small>
+Default level: <a href="../../rules#rule-levels" title="This lint has a default level of 'warn'."><code>warn</code></a> ·
+Added in <a href="https://github.com/astral-sh/ty/releases/tag/0.0.69">0.0.69</a> ·
+<a href="https://github.com/astral-sh/ty/issues?q=sort%3Aupdated-desc%20is%3Aissue%20is%3Aopen%20%22template-member-alters-data%22" target="_blank">Related issues</a> ·
+<a href="https://github.com/astral-sh/ruff/blob/main/crates%2Fty_python_semantic%2Fsrc%2Fdjango_template.rs#L324" target="_blank">View source</a>
+</small>
+
+
+**What it does**
+
+Checks for a `{{ }}` lookup landing on a method django refuses to call
+from a template.
+
+**Why is this bad?**
+
+Django calls whatever a lookup lands on, except a method marked
+`alters_data = True` — a template is not allowed to write to the
+database. Rather than call it, django renders `string_if_invalid` — the
+empty string by default — silently, with no error and no output.
+
+The methods django marks are the ones that write: `save`, `delete` and
+their `async` twins on a model, and the `create`/`update`/`bulk_*`
+family on a queryset, a manager and the manager behind a relation.
+Overriding one keeps the mark, so an override is reported too, exactly
+as django's own `AltersData` propagates it at runtime.
+
+**Examples**
+
+```django
+{{ book.save }}     {# warning: renders nothing #}
+{{ book.title }}    {# ok #}
+```
+
 ## `template-member-needs-arguments`
 
 <small>
 Default level: <a href="../../rules#rule-levels" title="This lint has a default level of 'warn'."><code>warn</code></a> ·
 Added in <a href="https://github.com/astral-sh/ty/releases/tag/0.0.69">0.0.69</a> ·
 <a href="https://github.com/astral-sh/ty/issues?q=sort%3Aupdated-desc%20is%3Aissue%20is%3Aopen%20%22template-member-needs-arguments%22" target="_blank">Related issues</a> ·
-<a href="https://github.com/astral-sh/ruff/blob/main/crates%2Fty_python_semantic%2Fsrc%2Fdjango_template.rs#L295" target="_blank">View source</a>
+<a href="https://github.com/astral-sh/ruff/blob/main/crates%2Fty_python_semantic%2Fsrc%2Fdjango_template.rs#L296" target="_blank">View source</a>
 </small>
 
 
@@ -6474,7 +6509,7 @@ class C(Generic[T]):
 Default level: <a href="../../rules#rule-levels" title="This lint has a default level of 'error'."><code>error</code></a> ·
 Added in <a href="https://github.com/astral-sh/ty/releases/tag/0.0.69">0.0.69</a> ·
 <a href="https://github.com/astral-sh/ty/issues?q=sort%3Aupdated-desc%20is%3Aissue%20is%3Aopen%20%22unclosed-template-block%22" target="_blank">Related issues</a> ·
-<a href="https://github.com/astral-sh/ruff/blob/main/crates%2Fty_python_semantic%2Fsrc%2Fdjango_template.rs#L34" target="_blank">View source</a>
+<a href="https://github.com/astral-sh/ruff/blob/main/crates%2Fty_python_semantic%2Fsrc%2Fdjango_template.rs#L35" target="_blank">View source</a>
 </small>
 
 
@@ -6658,7 +6693,7 @@ def test_thing(no_such_fixture) -> None:  # requests an unknown fixture
 Default level: <a href="../../rules#rule-levels" title="This lint has a default level of 'warn'."><code>warn</code></a> ·
 Added in <a href="https://github.com/astral-sh/ty/releases/tag/0.0.69">0.0.69</a> ·
 <a href="https://github.com/astral-sh/ty/issues?q=sort%3Aupdated-desc%20is%3Aissue%20is%3Aopen%20%22unknown-template-block%22" target="_blank">Related issues</a> ·
-<a href="https://github.com/astral-sh/ruff/blob/main/crates%2Fty_python_semantic%2Fsrc%2Fdjango_template.rs#L268" target="_blank">View source</a>
+<a href="https://github.com/astral-sh/ruff/blob/main/crates%2Fty_python_semantic%2Fsrc%2Fdjango_template.rs#L269" target="_blank">View source</a>
 </small>
 
 
@@ -6691,7 +6726,7 @@ part of its enclosing block and needs no declaration above it.
 Default level: <a href="../../rules#rule-levels" title="This lint has a default level of 'error'."><code>error</code></a> ·
 Added in <a href="https://github.com/astral-sh/ty/releases/tag/0.0.69">0.0.69</a> ·
 <a href="https://github.com/astral-sh/ty/issues?q=sort%3Aupdated-desc%20is%3Aissue%20is%3Aopen%20%22unknown-template-filter%22" target="_blank">Related issues</a> ·
-<a href="https://github.com/astral-sh/ruff/blob/main/crates%2Fty_python_semantic%2Fsrc%2Fdjango_template.rs#L125" target="_blank">View source</a>
+<a href="https://github.com/astral-sh/ruff/blob/main/crates%2Fty_python_semantic%2Fsrc%2Fdjango_template.rs#L126" target="_blank">View source</a>
 </small>
 
 
@@ -6719,7 +6754,7 @@ A filter whose library the template has simply not loaded is reported as
 Default level: <a href="../../rules#rule-levels" title="This lint has a default level of 'error'."><code>error</code></a> ·
 Added in <a href="https://github.com/astral-sh/ty/releases/tag/0.0.69">0.0.69</a> ·
 <a href="https://github.com/astral-sh/ty/issues?q=sort%3Aupdated-desc%20is%3Aissue%20is%3Aopen%20%22unknown-template-library%22" target="_blank">Related issues</a> ·
-<a href="https://github.com/astral-sh/ruff/blob/main/crates%2Fty_python_semantic%2Fsrc%2Fdjango_template.rs#L79" target="_blank">View source</a>
+<a href="https://github.com/astral-sh/ruff/blob/main/crates%2Fty_python_semantic%2Fsrc%2Fdjango_template.rs#L80" target="_blank">View source</a>
 </small>
 
 
@@ -6749,7 +6784,7 @@ reached is not a library that is missing.
 Default level: <a href="../../rules#rule-levels" title="This lint has a default level of 'error'."><code>error</code></a> ·
 Added in <a href="https://github.com/astral-sh/ty/releases/tag/0.0.69">0.0.69</a> ·
 <a href="https://github.com/astral-sh/ty/issues?q=sort%3Aupdated-desc%20is%3Aissue%20is%3Aopen%20%22unknown-template-tag%22" target="_blank">Related issues</a> ·
-<a href="https://github.com/astral-sh/ruff/blob/main/crates%2Fty_python_semantic%2Fsrc%2Fdjango_template.rs#L103" target="_blank">View source</a>
+<a href="https://github.com/astral-sh/ruff/blob/main/crates%2Fty_python_semantic%2Fsrc%2Fdjango_template.rs#L104" target="_blank">View source</a>
 </small>
 
 
@@ -6777,7 +6812,7 @@ A tag whose library the template has simply not loaded is reported as
 Default level: <a href="../../rules#rule-levels" title="This lint has a default level of 'error'."><code>error</code></a> ·
 Added in <a href="https://github.com/astral-sh/ty/releases/tag/0.0.69">0.0.69</a> ·
 <a href="https://github.com/astral-sh/ty/issues?q=sort%3Aupdated-desc%20is%3Aissue%20is%3Aopen%20%22unloaded-template-library%22" target="_blank">Related issues</a> ·
-<a href="https://github.com/astral-sh/ruff/blob/main/crates%2Fty_python_semantic%2Fsrc%2Fdjango_template.rs#L147" target="_blank">View source</a>
+<a href="https://github.com/astral-sh/ruff/blob/main/crates%2Fty_python_semantic%2Fsrc%2Fdjango_template.rs#L148" target="_blank">View source</a>
 </small>
 
 
@@ -6805,7 +6840,7 @@ every template already and is never reported.
 Default level: <a href="../../rules#rule-levels" title="This lint has a default level of 'error'."><code>error</code></a> ·
 Added in <a href="https://github.com/astral-sh/ty/releases/tag/0.0.69">0.0.69</a> ·
 <a href="https://github.com/astral-sh/ty/issues?q=sort%3Aupdated-desc%20is%3Aissue%20is%3Aopen%20%22unmatched-template-close%22" target="_blank">Related issues</a> ·
-<a href="https://github.com/astral-sh/ruff/blob/main/crates%2Fty_python_semantic%2Fsrc%2Fdjango_template.rs#L57" target="_blank">View source</a>
+<a href="https://github.com/astral-sh/ruff/blob/main/crates%2Fty_python_semantic%2Fsrc%2Fdjango_template.rs#L58" target="_blank">View source</a>
 </small>
 
 
@@ -7028,7 +7063,7 @@ print(x)  # error
 Default level: <a href="../../rules#rule-levels" title="This lint has a default level of 'error'."><code>error</code></a> ·
 Added in <a href="https://github.com/astral-sh/ty/releases/tag/0.0.69">0.0.69</a> ·
 <a href="https://github.com/astral-sh/ty/issues?q=sort%3Aupdated-desc%20is%3Aissue%20is%3Aopen%20%22unresolved-route%22" target="_blank">Related issues</a> ·
-<a href="https://github.com/astral-sh/ruff/blob/main/crates%2Fty_python_semantic%2Fsrc%2Fdjango_template.rs#L217" target="_blank">View source</a>
+<a href="https://github.com/astral-sh/ruff/blob/main/crates%2Fty_python_semantic%2Fsrc%2Fdjango_template.rs#L218" target="_blank">View source</a>
 </small>
 
 
@@ -7058,7 +7093,7 @@ walked in full, reports nothing.
 Default level: <a href="../../rules#rule-levels" title="This lint has a default level of 'warn'."><code>warn</code></a> ·
 Added in <a href="https://github.com/astral-sh/ty/releases/tag/0.0.69">0.0.69</a> ·
 <a href="https://github.com/astral-sh/ty/issues?q=sort%3Aupdated-desc%20is%3Aissue%20is%3Aopen%20%22unresolved-static-file%22" target="_blank">Related issues</a> ·
-<a href="https://github.com/astral-sh/ruff/blob/main/crates%2Fty_python_semantic%2Fsrc%2Fdjango_template.rs#L193" target="_blank">View source</a>
+<a href="https://github.com/astral-sh/ruff/blob/main/crates%2Fty_python_semantic%2Fsrc%2Fdjango_template.rs#L194" target="_blank">View source</a>
 </small>
 
 
@@ -7088,7 +7123,7 @@ not something the source tree can answer.
 Default level: <a href="../../rules#rule-levels" title="This lint has a default level of 'error'."><code>error</code></a> ·
 Added in <a href="https://github.com/astral-sh/ty/releases/tag/0.0.69">0.0.69</a> ·
 <a href="https://github.com/astral-sh/ty/issues?q=sort%3Aupdated-desc%20is%3Aissue%20is%3Aopen%20%22unresolved-template%22" target="_blank">Related issues</a> ·
-<a href="https://github.com/astral-sh/ruff/blob/main/crates%2Fty_python_semantic%2Fsrc%2Fdjango_template.rs#L169" target="_blank">View source</a>
+<a href="https://github.com/astral-sh/ruff/blob/main/crates%2Fty_python_semantic%2Fsrc%2Fdjango_template.rs#L170" target="_blank">View source</a>
 </small>
 
 
diff --git a/crates/ty_ide/src/django_template.rs b/crates/ty_ide/src/django_template.rs
index b46ac4c314..fea452cef9 100644
--- a/crates/ty_ide/src/django_template.rs
+++ b/crates/ty_ide/src/django_template.rs
@@ -754,6 +754,15 @@ pub(crate) mod tests {
                 .collect()
         }
 
+        /// the labels of the completions at the cursor django will not render
+        pub(crate) fn unusable(&self) -> Vec<String> {
+            django_template_completions(&self.db, self.file, self.offset)
+                .into_iter()
+                .filter(|completion| completion.unusable)
+                .map(|completion| completion.label)
+                .collect()
+        }
+
         /// the completions at the cursor, rendered as `label — detail`
         pub(crate) fn detailed(&self) -> Vec<String> {
             django_template_completions(&self.db, self.file, self.offset)
diff --git a/crates/ty_ide/src/django_template/completion.rs b/crates/ty_ide/src/django_template/completion.rs
index 3b11d8ab39..71a2781cab 100644
--- a/crates/ty_ide/src/django_template/completion.rs
+++ b/crates/ty_ide/src/django_template/completion.rs
@@ -17,6 +17,7 @@ use ruff_db::files::File;
 use ruff_text_size::{TextRange, TextSize};
 use rustc_hash::FxHashSet;
 use ty_project::Db;
+use ty_python_semantic::types::ide_support::{TemplateLookup, template_lookup};
 
 use crate::completion::CompletionKind;
 
@@ -53,6 +54,12 @@ pub struct TemplateCompletion {
     pub range: TextRange,
     /// the `{% load %}` the suggestion needs, when its library isn't loaded yet
     pub additional_edit: Option<TemplateEdit>,
+    /// whether the member is one django will not render
+    ///
+    /// it is still offered, because it is genuinely there and a template author
+    /// reading `{{ book.save }}` deserves to be told what it is rather than
+    /// shown nothing. the client strikes it through.
+    pub unusable: bool,
 }
 
 impl TemplateCompletion {
@@ -65,9 +72,16 @@ impl TemplateCompletion {
             insert: None,
             range,
             additional_edit: None,
+            unusable: false,
         }
     }
 
+    #[must_use]
+    fn unusable(mut self, unusable: bool) -> Self {
+        self.unusable = unusable;
+        self
+    }
+
     #[must_use]
     fn detail(mut self, detail: impl Into<String>) -> Self {
         self.detail = Some(detail.into());
@@ -606,13 +620,22 @@ fn members(
         return Vec::new();
     };
 
-    resolve::members(db, ty)
+    let mut members: Vec<_> = resolve::members(db, ty)
         .into_iter()
         .map(|member| {
+            let refused =
+                template_lookup(db, ty, &member.name, member.ty) == TemplateLookup::Refuses;
+
             TemplateCompletion::new(member.name.as_str(), CompletionKind::Field, cursor.range)
                 .detail(member.ty.display(db).to_string())
+                .unusable(refused)
         })
-        .collect()
+        .collect();
+
+    // a member django will not render belongs below every member it will,
+    // whichever class declared it
+    members.sort_by_key(|member| member.unusable);
+    members
 }
 
 fn variables(
@@ -1846,4 +1869,143 @@ mod tests {
                 .contains(&"slugify".to_string())
         );
     }
+
+    /// a project whose model really is a `django.db.models.Model`, so that the
+    /// members django marks `alters_data` are the ones django marks
+    fn with_a_real_model(template: &str) -> TemplateTest {
+        TemplateTest::with_site_packages(
+            &[
+                (
+                    "manage.py",
+                    "
+                    import os
+
+                    os.environ.setdefault('DJANGO_SETTINGS_MODULE', 'project.settings')
+                    ",
+                ),
+                ("project/__init__.py", ""),
+                (
+                    "project/settings.py",
+                    "
+                    INSTALLED_APPS = ['blog']
+
+                    TEMPLATES = [{'APP_DIRS': True, 'OPTIONS': {}}]
+                    ",
+                ),
+                ("blog/__init__.py", ""),
+                (
+                    "blog/models.py",
+                    "
+                    from typing import Literal
+
+                    from django.db.models import Model
+
+
+                    class Section:
+                        heading: str
+
+
+                    class Sections:
+                        # django reads this off the member and uses it as it is
+                        do_not_call_in_templates: Literal[True]
+
+                        def __call__(self) -> Section: ...
+
+                        def first(self) -> Section: ...
+
+
+                    class Page(Model):
+                        number: int
+                        sections: Sections
+                    ",
+                ),
+                (
+                    "blog/views.py",
+                    "
+                    from blog.models import Page
+
+
+                    def post(request):
+                        return render(request, 'blog/post.html', {'page': Page()})
+                    ",
+                ),
+                ("blog/templates/blog/post.html", template),
+            ],
+            &[
+                ("django/__init__.py", ""),
+                ("django/db/__init__.py", ""),
+                (
+                    "django/db/models/__init__.py",
+                    "from django.db.models.base import Model",
+                ),
+                (
+                    "django/db/models/utils.py",
+                    "
+                    class AltersData:
+                        def __init_subclass__(cls, **kwargs) -> None: ...
+                    ",
+                ),
+                (
+                    "django/db/models/base.py",
+                    "
+                    from django.db.models.utils import AltersData
+
+
+                    class Model(AltersData):
+                        pk: int
+
+                        def save(self) -> None: ...
+
+                        def delete(self) -> None: ...
+
+                        def refresh_from_db(self) -> None: ...
+                    ",
+                ),
+            ],
+        )
+    }
+
+    #[test]
+    fn a_member_django_will_not_render_is_marked_rather_than_hidden() {
+        let completions = with_a_real_model("{{ page.<CURSOR> }}");
+
+        assert_eq!(completions.unusable(), ["delete", "save"]);
+        assert!(completions.completions().contains(&"save".to_string()));
+    }
+
+    #[test]
+    fn a_member_django_will_not_render_sorts_below_every_member_it_will() {
+        let completions = with_a_real_model("{{ page.<CURSOR> }}").completions();
+        let usable = completions.len() - 2;
+
+        assert_eq!(&completions[usable..], ["delete", "save"]);
+    }
+
+    #[test]
+    fn nothing_is_offered_past_a_member_django_refuses_to_call() {
+        assert!(
+            with_a_real_model("{{ page.save.<CURSOR> }}")
+                .completions()
+                .is_empty()
+        );
+    }
+
+    #[test]
+    fn a_member_marked_do_not_call_in_templates_keeps_its_own_members() {
+        // calling it would give a `Section`, and `heading` with it. django does
+        // not call it, so `first` is what the template can reach
+        let completions = with_a_real_model("{{ page.sections.<CURSOR> }}").completions();
+
+        assert!(completions.contains(&"first".to_string()));
+        assert!(!completions.contains(&"heading".to_string()));
+    }
+
+    #[test]
+    fn a_member_django_renders_is_not_marked() {
+        assert!(
+            !with_a_real_model("{{ page.<CURSOR> }}")
+                .unusable()
+                .contains(&"refresh_from_db".to_string())
+        );
+    }
 }
diff --git a/crates/ty_ide/src/django_template/diagnostics.rs b/crates/ty_ide/src/django_template/diagnostics.rs
index 0aa57674ed..a1bfa21882 100644
--- a/crates/ty_ide/src/django_template/diagnostics.rs
+++ b/crates/ty_ide/src/django_template/diagnostics.rs
@@ -22,13 +22,15 @@ use ruff_text_size::{TextRange, TextSize};
 use rustc_hash::FxHashSet;
 use ty_project::Db;
 use ty_python_semantic::django_template::{
-    INVALID_ROUTE_ARGUMENTS, TEMPLATE_MEMBER_NEEDS_ARGUMENTS, UNCLOSED_TEMPLATE_BLOCK,
-    UNKNOWN_TEMPLATE_BLOCK, UNKNOWN_TEMPLATE_FILTER, UNKNOWN_TEMPLATE_LIBRARY,
-    UNKNOWN_TEMPLATE_TAG, UNLOADED_TEMPLATE_LIBRARY, UNMATCHED_TEMPLATE_CLOSE, UNRESOLVED_ROUTE,
-    UNRESOLVED_STATIC_FILE, UNRESOLVED_TEMPLATE,
+    INVALID_ROUTE_ARGUMENTS, TEMPLATE_MEMBER_ALTERS_DATA, TEMPLATE_MEMBER_NEEDS_ARGUMENTS,
+    UNCLOSED_TEMPLATE_BLOCK, UNKNOWN_TEMPLATE_BLOCK, UNKNOWN_TEMPLATE_FILTER,
+    UNKNOWN_TEMPLATE_LIBRARY, UNKNOWN_TEMPLATE_TAG, UNLOADED_TEMPLATE_LIBRARY,
+    UNMATCHED_TEMPLATE_CLOSE, UNRESOLVED_ROUTE, UNRESOLVED_STATIC_FILE, UNRESOLVED_TEMPLATE,
 };
 use ty_python_semantic::lint::{LintId, LintMetadata};
-use ty_python_semantic::types::ide_support::callable_needs_arguments;
+use ty_python_semantic::types::ide_support::{
+    TemplateLookup, callable_needs_arguments, template_lookup,
+};
 
 use crate::code_action::QuickFix;
 
@@ -641,10 +643,19 @@ impl Checker<'_> {
         })
     }
 
-    // ---- 12. a lookup landing on a method that needs arguments -------------
+    // ---- 12. a lookup landing on a member django will not call -------------
 
+    /// the two ways a `{{ }}` lookup can land on a method and render nothing:
+    /// django refuses to call it, or django tries and cannot
+    ///
+    /// both are read off the same walk because both end the path — once a
+    /// segment renders nothing, the segments after it have nothing to resolve
+    /// against — and because they are checked in django's own order: it consults
+    /// `alters_data` before it attempts the call, so a write method that also
+    /// needs arguments is refused rather than uncallable.
     fn members_needing_arguments(&mut self) {
         let mut found = Vec::new();
+        let mut refused = Vec::new();
 
         for construct in self.index.lexed().constructs() {
             if construct.kind != ConstructKind::Variable {
@@ -665,13 +676,18 @@ impl Checker<'_> {
                     ) else {
                         break;
                     };
-                    let Some(member) = resolve::uncalled_member_type(self.db, ty, segments[length])
-                    else {
+                    let name = segments[length];
+                    let Some(member) = resolve::uncalled_member_type(self.db, ty, name) else {
                         break;
                     };
 
+                    if template_lookup(self.db, ty, name, member) == TemplateLookup::Refuses {
+                        refused.push((name.to_compact_string(), path[length].range));
+                        break;
+                    }
+
                     if callable_needs_arguments(self.db, member) {
-                        found.push((segments[length].to_compact_string(), path[length].range));
+                        found.push((name.to_compact_string(), path[length].range));
                         break;
                     }
                 }
@@ -687,6 +703,16 @@ impl Checker<'_> {
                 diagnostic.help("django renders nothing for a member it cannot call");
             }
         }
+
+        for (name, range) in refused {
+            if let Some(diagnostic) = self.report(
+                &TEMPLATE_MEMBER_ALTERS_DATA,
+                range,
+                format_args!("django will not call `{name}` from a template"),
+            ) {
+                diagnostic.help("`alters_data` marks it, so django renders nothing instead");
+            }
+        }
     }
 
     // ---- reading a construct's arguments -----------------------------------
@@ -1085,6 +1111,9 @@ mod tests {
                 (
                     "blog/models.py",
                     "
+                    from django.db.models import Model
+
+
                     class Book:
                         pk: int
                         title: str
@@ -1094,16 +1123,32 @@ mod tests {
 
                         def excerpt(self, length: int) -> str:
                             return self.title[:length]
+
+                        def save(self) -> None:
+                            return None
+
+
+                    class Page(Model):
+                        number: int
+
+                        # a name of django's own, overridden. django's own
+                        # `AltersData` copies the mark onto an override
+                        def delete(self) -> None:
+                            return None
+
+                        # a name django marks on a queryset but not on a model
+                        def update(self) -> str:
+                            return ''
                     ",
                 ),
                 (
                     "blog/views.py",
                     "
-                    from blog.models import Book
+                    from blog.models import Book, Page
 
 
                     def post(request):
-                        return render(request, 'blog/post.html', {'book': Book()})
+                        return render(request, 'blog/post.html', {'book': Book(), 'page': Page()})
                     ",
                 ),
                 (
@@ -1154,6 +1199,34 @@ mod tests {
             ],
             &[
                 ("django/__init__.py", ""),
+                ("django/db/__init__.py", ""),
+                (
+                    "django/db/models/__init__.py",
+                    "from django.db.models.base import Model",
+                ),
+                (
+                    "django/db/models/utils.py",
+                    "
+                    class AltersData:
+                        def __init_subclass__(cls, **kwargs) -> None: ...
+                    ",
+                ),
+                (
+                    "django/db/models/base.py",
+                    "
+                    from django.db.models.utils import AltersData
+
+
+                    class Model(AltersData):
+                        pk: int
+
+                        def save(self) -> None: ...
+
+                        def delete(self) -> None: ...
+
+                        def refresh_from_db(self) -> None: ...
+                    ",
+                ),
                 ("django/templatetags/__init__.py", ""),
                 (
                     "django/templatetags/static.py",
@@ -1724,6 +1797,55 @@ mod tests {
         );
     }
 
+    #[test]
+    fn a_member_django_refuses_to_call_is_reported() {
+        assert_eq!(
+            project("{{ page.save }}\n").diagnostics(),
+            [
+                "template-member-alters-data Warning: django will not call `save` from a template [save]"
+            ]
+        );
+    }
+
+    #[test]
+    fn an_override_of_a_member_django_refuses_to_call_is_reported() {
+        assert_eq!(
+            project("{{ page.delete }}\n").diagnostics(),
+            [
+                "template-member-alters-data Warning: django will not call `delete` from a template [delete]"
+            ]
+        );
+    }
+
+    #[test]
+    fn a_member_of_the_projects_own_class_is_not_reported() {
+        assert!(project("{{ book.save }}\n").diagnostics().is_empty());
+    }
+
+    #[test]
+    fn a_model_method_django_has_no_equivalent_of_is_not_reported() {
+        assert!(project("{{ page.update }}\n").diagnostics().is_empty());
+    }
+
+    #[test]
+    fn a_model_member_django_calls_is_not_reported() {
+        assert!(
+            project("{{ page.number }}{{ page.refresh_from_db }}\n")
+                .diagnostics()
+                .is_empty()
+        );
+    }
+
+    #[test]
+    fn a_path_continuing_through_a_refused_member_is_reported_once() {
+        assert_eq!(
+            project("{{ page.save.anything }}\n").diagnostics(),
+            [
+                "template-member-alters-data Warning: django will not call `save` from a template [save]"
+            ]
+        );
+    }
+
     #[test]
     fn a_suppression_on_the_same_line_silences_the_line() {
         assert!(
diff --git a/crates/ty_ide/src/django_template/resolve.rs b/crates/ty_ide/src/django_template/resolve.rs
index 12de421671..1b8713a339 100644
--- a/crates/ty_ide/src/django_template/resolve.rs
+++ b/crates/ty_ide/src/django_template/resolve.rs
@@ -14,7 +14,8 @@ use ruff_text_size::{Ranged, TextRange, TextSize};
 use ty_project::Db;
 use ty_python_semantic::types::Type;
 use ty_python_semantic::types::ide_support::{
-    iterable_element_type, no_argument_call_return_type, own_class_member_names,
+    TemplateLookup, iterable_element_type, no_argument_call_return_type, own_class_member_names,
+    template_lookup,
 };
 use ty_python_semantic::types::list_members::{Member, all_members};
 use ty_python_semantic::{HasType, SemanticModel};
@@ -207,7 +208,17 @@ pub(crate) fn path_segments<'src>(
 ///
 /// [resolved]: https://docs.djangoproject.com/en/stable/ref/templates/language/#variables
 pub(crate) fn member_type<'db>(db: &'db dyn Db, ty: Type<'db>, name: &str) -> Option<Type<'db>> {
-    Some(resolved(db, uncalled_member_type(db, ty, name)?))
+    let member = uncalled_member_type(db, ty, name)?;
+
+    match template_lookup(db, ty, name, member) {
+        TemplateLookup::Calls => Some(resolved(db, member)),
+        TemplateLookup::UsesUncalled => Some(member),
+        // django renders `string_if_invalid` here, which is configurable and by
+        // default the empty string. nothing useful can be said about a path
+        // continuing through it, and saying `str` would offer `upper` on what a
+        // template cannot read at all
+        TemplateLookup::Refuses => None,
+    }
 }
 
 /// the type of `name` accessed on `ty`, before the template engine calls it
diff --git a/crates/ty_python_semantic/src/django_template.rs b/crates/ty_python_semantic/src/django_template.rs
index 3f0e7357a5..2106828419 100644
--- a/crates/ty_python_semantic/src/django_template.rs
+++ b/crates/ty_python_semantic/src/django_template.rs
@@ -27,6 +27,7 @@ pub(crate) fn register_lints(registry: &mut LintRegistryBuilder) {
     registry.register_lint(&INVALID_ROUTE_ARGUMENTS);
     registry.register_lint(&UNKNOWN_TEMPLATE_BLOCK);
     registry.register_lint(&TEMPLATE_MEMBER_NEEDS_ARGUMENTS);
+    registry.register_lint(&TEMPLATE_MEMBER_ALTERS_DATA);
     registry.register_lint(&INVALID_ROUTE_HANDLER);
     registry.register_lint(&INVALID_ROUTE_PARAMETER_TYPE);
 }
@@ -320,6 +321,35 @@ declare_lint! {
     }
 }
 
+declare_lint! {
+    /// ## What it does
+    /// Checks for a `{{ }}` lookup landing on a method django refuses to call
+    /// from a template.
+    ///
+    /// ## Why is this bad?
+    /// Django calls whatever a lookup lands on, except a method marked
+    /// `alters_data = True` — a template is not allowed to write to the
+    /// database. Rather than call it, django renders `string_if_invalid` — the
+    /// empty string by default — silently, with no error and no output.
+    ///
+    /// The methods django marks are the ones that write: `save`, `delete` and
+    /// their `async` twins on a model, and the `create`/`update`/`bulk_*`
+    /// family on a queryset, a manager and the manager behind a relation.
+    /// Overriding one keeps the mark, so an override is reported too, exactly
+    /// as django's own `AltersData` propagates it at runtime.
+    ///
+    /// ## Examples
+    /// ```django
+    /// {{ book.save }}     {# warning: renders nothing #}
+    /// {{ book.title }}    {# ok #}
+    /// ```
+    pub static TEMPLATE_MEMBER_ALTERS_DATA = {
+        summary: "detects a template lookup landing on a method django refuses to call",
+        status: LintStatus::stable("0.0.69"),
+        default_level: Level::Warn,
+    }
+}
+
 declare_lint! {
     /// ## What it does
     /// Checks that the view a route names can take the arguments the route's
diff --git a/crates/ty_python_semantic/src/types/dedicated/django.rs b/crates/ty_python_semantic/src/types/dedicated/django.rs
index 3c8d22a314..99ba452b1f 100644
--- a/crates/ty_python_semantic/src/types/dedicated/django.rs
+++ b/crates/ty_python_semantic/src/types/dedicated/django.rs
@@ -21,6 +21,7 @@ use ty_python_core::{global_scope, place_table, use_def_map};
 
 use crate::place::{Place, known_module_symbol};
 use crate::types::class::{CodeGeneratorKind, Field, FieldKind};
+use crate::types::list_members::all_end_of_scope_members;
 use crate::types::member::class_member;
 use crate::types::signatures::{Parameter, Parameters, Signature};
 use crate::types::{
@@ -1270,3 +1271,122 @@ pub(in crate::types) fn with_queryset_row<'db>(
         });
     Some(Type::instance(db, class_type))
 }
+
+/// the methods django marks `alters_data = True`
+///
+/// django's template variable resolution refuses to call one of these and
+/// renders `string_if_invalid` instead, so a template that names one silently
+/// renders nothing.
+///
+/// the mark is written on the function object (`save.alters_data = True`,
+/// `django/db/models/base.py`), which is a form no stub can express and
+/// `django-stubs` declares nowhere — grepping the package for `alters_data`
+/// finds nothing. so unlike the rest of this module, which re-derives what it
+/// needs from what the stubs declare, these names are django's own, read off
+/// django's source. [`refuses_template_call`] is what keeps them from matching
+/// anything but django's own methods.
+///
+/// django's underscore-prefixed marks (`_insert`, `_update`, `_raw_delete`,
+/// `_clear`) are left out: a template cannot write a name beginning with `_`.
+/// sorted, for [`slice::binary_search`]
+const ALTERS_DATA_METHODS: &[&str] = &[
+    "aadd",
+    "abulk_create",
+    "abulk_update",
+    "aclear",
+    "acreate",
+    "acreate_superuser",
+    "acreate_user",
+    "add",
+    "adelete",
+    "aget_or_create",
+    "aremove",
+    "asave",
+    "aset",
+    "aupdate",
+    "aupdate_or_create",
+    "bulk_create",
+    "bulk_update",
+    "clear",
+    "create",
+    "create_superuser",
+    "create_user",
+    "delete",
+    "get_or_create",
+    "open",
+    "remove",
+    "save",
+    "save_base",
+    "set",
+    "update",
+    "update_or_create",
+];
+
+/// whether django's template variable resolution refuses to call `name` on
+/// `receiver`
+///
+/// three things have to hold, and each rules out a different way the name could
+/// belong to something other than django:
+///
+/// - `receiver` is one of django's classes whose methods carry the mark: one
+///   deriving `AltersData`, the base django gives exactly those, or a manager or
+///   queryset. the managers derive it at runtime too, but `django-stubs`
+///   declares `BaseManager` without it, so they are recognized the way the rest
+///   of this module recognizes them. a plain class of the project's own with a
+///   `save` method is neither
+/// - one of django's own classes in the mro declares `name`. a model may add a
+///   method django has no equivalent of, and django does not mark that one — the
+///   propagation in `AltersData.__init_subclass__` only copies a mark a base
+///   already has. an *override* of django's method is still reported, which is
+///   what that propagation does at runtime
+/// - the member is a method rather than a value. a model is free to call a field
+///   `update`, and django renders a field
+pub(in crate::types) fn refuses_template_call<'db>(
+    db: &'db dyn Db,
+    receiver: Type<'db>,
+    name: &str,
+    member: Type<'db>,
+) -> bool {
+    if ALTERS_DATA_METHODS.binary_search(&name).is_err() {
+        return false;
+    }
+    if !matches!(member, Type::FunctionLiteral(_) | Type::BoundMethod(_)) {
+        return false;
+    }
+    let Some(class) = instance_static_class(db, receiver) else {
+        return false;
+    };
+
+    let marks_its_methods = has_base_named(db, class, "django.db.models.utils", "AltersData")
+        || has_base(db, class, KnownClass::DjangoManager)
+        || has_base(db, class, KnownClass::DjangoQuerySet);
+
+    marks_its_methods && declared_by_django(db, class, name)
+}
+
+/// whether a class of django's own in `class`'s mro declares `name` itself
+fn declared_by_django<'db>(db: &'db dyn Db, class: StaticClassLiteral<'db>, name: &str) -> bool {
+    class
+        .iter_mro(db, None)
+        .filter_map(ClassBase::into_class)
+        .filter_map(|candidate| candidate.class_literal(db).as_static())
+        .filter(|candidate| {
+            file_to_module(db, candidate.file(db))
+                .is_some_and(|module| module.name(db).as_str().starts_with("django."))
+        })
+        .any(|candidate| {
+            all_end_of_scope_members(db, candidate.body_scope(db))
+                .any(|member| member.member.name == name)
+        })
+}
+
+#[cfg(test)]
+mod tests {
+    use super::ALTERS_DATA_METHODS;
+
+    #[test]
+    fn the_marked_methods_are_sorted() {
+        // `refuses_template_call` binary-searches them
+        assert!(ALTERS_DATA_METHODS.windows(2).all(|pair| pair[0] < pair[1]));
+    }
+}
diff --git a/crates/ty_python_semantic/src/types/ide_support.rs b/crates/ty_python_semantic/src/types/ide_support.rs
index cc81fc0d8f..5fe52d6035 100644
--- a/crates/ty_python_semantic/src/types/ide_support.rs
+++ b/crates/ty_python_semantic/src/types/ide_support.rs
@@ -7,6 +7,7 @@ use crate::types::call::bind::CheckTypesMode;
 use crate::types::call::{CallArguments, CallError, MatchedArgument};
 use crate::types::class::{DynamicClassAnchor, DynamicEnumAnchor, DynamicNamedTupleAnchor};
 use crate::types::constraints::ConstraintSetBuilder;
+use crate::types::dedicated::django;
 use crate::types::function::FunctionDecorators;
 use crate::types::generics::GenericContext;
 use crate::types::list_members::all_end_of_scope_members;
@@ -2575,6 +2576,62 @@ pub fn callable_needs_arguments<'db>(db: &'db dyn Db, ty: Type<'db>) -> bool {
         && no_argument_call_return_type(db, ty).is_none()
 }
 
+/// What django's template variable resolution does with the member a lookup
+/// found.
+///
+/// Django calls whatever a lookup lands on, but two attributes it reads off the
+/// member itself say otherwise, and `Variable._resolve_lookup` reads them in the
+/// order these variants are written in:
+///
+/// ```python
+/// if callable(current):
+///     if getattr(current, "do_not_call_in_templates", False):
+///         pass
+///     elif getattr(current, "alters_data", False):
+///         current = context.template.engine.string_if_invalid
+///     else:
+///         current = current()
+/// ```
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum TemplateLookup {
+    /// Django calls it, so the lookup contributes what the call returns.
+    Calls,
+    /// `do_not_call_in_templates`: django uses the member itself, uncalled.
+    /// Django's `Choices` classes carry it, as do the managers behind a
+    /// relation, so that `{{ author.book_set }}` names the manager rather than
+    /// whatever calling it would give.
+    UsesUncalled,
+    /// `alters_data`: django refuses, and renders `string_if_invalid` — the
+    /// empty string by default.
+    Refuses,
+}
+
+/// What django's template variable resolution does with `name` on `receiver`.
+///
+/// `member` is the type of `name` on `receiver` before django has done anything
+/// with it — [`TemplateLookup::Calls`] is the only answer under which the lookup
+/// contributes a return type rather than the member itself.
+pub fn template_lookup<'db>(
+    db: &'db dyn Db,
+    receiver: Type<'db>,
+    name: &str,
+    member: Type<'db>,
+) -> TemplateLookup {
+    let declares_do_not_call = member
+        .member(db, "do_not_call_in_templates")
+        .place
+        .ignore_possibly_undefined()
+        .is_some_and(|flag| flag.bool(db).is_always_true());
+
+    if declares_do_not_call {
+        TemplateLookup::UsesUncalled
+    } else if django::refuses_template_call(db, receiver, name, member) {
+        TemplateLookup::Refuses
+    } else {
+        TemplateLookup::Calls
+    }
+}
+
 /// The names `ty`'s own class declares, as opposed to the ones it inherits.
 ///
 /// Written for django templates, where a model's own fields have to be told
diff --git a/crates/ty_server/src/server/api/requests/completion.rs b/crates/ty_server/src/server/api/requests/completion.rs
index 0eebecb98e..8eda65062e 100644
--- a/crates/ty_server/src/server/api/requests/completion.rs
+++ b/crates/ty_server/src/server/api/requests/completion.rs
@@ -283,6 +283,12 @@ fn django_template_completions(
                     .as_ref()
                     .and_then(to_edit)
                     .map(|edit| vec![edit]),
+                // a member django will not render is struck through rather than
+                // dropped: it is really there, and hiding it would leave someone
+                // typing `book.sa` with no answer at all
+                tags: completion
+                    .unusable
+                    .then(|| vec![lsp_types::CompletionItemTag::Deprecated]),
                 ..Default::default()
             }
         })
diff --git a/docs/basedpython/frameworks/django-templates.md b/docs/basedpython/frameworks/django-templates.md
index bf73e3761f..cd44076fa2 100644
--- a/docs/basedpython/frameworks/django-templates.md
+++ b/docs/basedpython/frameworks/django-templates.md
@@ -154,6 +154,17 @@ a lookup that lands on something callable is called, exactly as django calls it,
 
 a method that needs an argument is not called — django renders nothing for it, and neither does the server offer anything past it.
 
+django refuses outright to call a method marked `alters_data`, and renders nothing instead of writing to the database from a template. those resolve to nothing too, and are reported:
+
+```django
+{{ book.save }}                {# warning: django will not call `save` from a template #}
+{{ book.author.book_set.create }}
+```
+
+the ones it marks are `save`, `delete` and their `async` twins on a model, and the `create`/`update`/`bulk_*` family on a queryset, a manager and the manager behind a relation. overriding one keeps the mark, so an override is reported too.
+
+going the other way, a member marked `do_not_call_in_templates` is used as it is rather than called — django's `Choices` classes carry it, so `{{ Color.RED }}` is the member and not whatever calling it would give.
+
 the same works through the template's own bindings:
 
 ```django
@@ -221,7 +232,9 @@ a project whose settings cannot be read, or whose django cannot be resolved at a
 
 **the context has to be written where it is passed.** the names are read out of the dict literal in the `render()` call or the view class, so a context built somewhere else and passed by name — `return render(request, "…", context)` — contributes nothing.
 
-**a member django refuses to call is still offered.** django won't call `save()` or `delete()` from a template — they carry `alters_data` — but `django-stubs` doesn't record that, so there is nothing to read it from. they appear in the list, below the model's own fields.
+**a member django refuses to call is still offered, struck through.** it is genuinely there, and someone reading `{{ book.save }}` is better served by being told what it is than by being shown nothing, so it is marked and sorted below every member django will render rather than hidden.
+
+**`alters_data` is django's own set rather than something read off the code.** django writes the mark on the function object, which no stub can express and `django-stubs` declares nowhere — grepping the package finds nothing. so the names come from django's source, and only apply to django's own classes: a class of the project's own with a `save` method is not reported, and neither is a method a model adds that django has no equivalent of.
 
 **dictionary lookups don't resolve.** django tries a subscript before an attribute, so `{{ mapping.key }}` works at runtime, but a mapping's keys are values rather than types and completions can only offer attributes.
 
diff --git a/ty.schema.json b/ty.schema.json
index 6c11540744..87b3f98e8a 100644
--- a/ty.schema.json
+++ b/ty.schema.json
@@ -1880,6 +1880,16 @@
             }
           ]
         },
+        "template-member-alters-data": {
+          "title": "detects a template lookup landing on a method django refuses to call",
+          "description": "## What it does\nChecks for a `{{ }}` lookup landing on a method django refuses to call\nfrom a template.\n\n## Why is this bad?\nDjango calls whatever a lookup lands on, except a method marked\n`alters_data = True` — a template is not allowed to write to the\ndatabase. Rather than call it, django renders `string_if_invalid` — the\nempty string by default — silently, with no error and no output.\n\nThe methods django marks are the ones that write: `save`, `delete` and\ntheir `async` twins on a model, and the `create`/`update`/`bulk_*`\nfamily on a queryset, a manager and the manager behind a relation.\nOverriding one keeps the mark, so an override is reported too, exactly\nas django's own `AltersData` propagates it at runtime.\n\n## Examples\n```django\n{{ book.save }}     {# warning: renders nothing #}\n{{ book.title }}    {# ok #}\n```",
+          "default": "warn",
+          "oneOf": [
+            {
+              "$ref": "#/definitions/Level"
+            }
+          ]
+        },
         "template-member-needs-arguments": {
           "title": "detects a template lookup landing on a method that needs arguments",
           "description": "## What it does\nChecks for a `{{ }}` lookup landing on a method that cannot be called\nwithout arguments.\n\n## Why is this bad?\nDjango calls whatever a lookup lands on. A method that needs an argument\ncannot be called, so django renders `string_if_invalid` — the empty string\nby default — silently, with no error and no output.\n\n## Examples\n```python\nclass Book:\n    def headline(self, length: int) -> str: ...\n    def title(self) -> str: ...\n```\n\n```django\n{{ book.headline }}    {# warning: renders nothing #}\n{{ book.title }}       {# ok #}\n```",

From 203ca69968b8afc377a543ef1923c34723c81963 Mon Sep 17 00:00:00 2001
From: KotlinIsland <65446343+kotlinisland@users.noreply.github.com>
Date: Sat, 8 Aug 2026 21:38:32 +1000
Subject: [PATCH 10/16] a drf view and serializer say their model in the class
 body

`get_queryset`, `get_object`, `get_serializer` and `save` specialize from the
view's own `queryset` and the serializer's `Meta.model`, which the stubs leave as
`Unknown` and their mypy plugin derives nothing from

`data` and `validated_data` stay `Any` deliberately: `validate()` may drop and
invent keys freely, so the key set is *open* rather than merely optional, and a
closed type there would turn correct code into errors
---
 .../resources/mdtest/external/drf.md          | 213 ++++++++++++++
 .../ty_python_semantic/src/types/call/bind.rs |  22 ++
 .../src/types/dedicated/django.rs             | 259 +++++++++++++++---
 docs/basedpython/frameworks/django.md         |  45 +++
 4 files changed, 503 insertions(+), 36 deletions(-)

diff --git a/crates/ty_python_semantic/resources/mdtest/external/drf.md b/crates/ty_python_semantic/resources/mdtest/external/drf.md
index ab60b594fa..df1e988349 100644
--- a/crates/ty_python_semantic/resources/mdtest/external/drf.md
+++ b/crates/ty_python_semantic/resources/mdtest/external/drf.md
@@ -5,6 +5,10 @@ class-body lists of plain strings, so a typo survives the stubs and only fails a
 serializer is first built, or when a request asks for that ordering / search / filter. ty resolves
 each literal entry against the model the declaring class names.
 
+`missing-type-argument` is put back to its default level here: real drf code subclasses
+`ModelSerializer` and `ListAPIView` without writing the type argument, and what the class body says
+instead is the subject of half of these tests.
+
 ```toml
 [environment]
 python-version = "3.13"
@@ -17,6 +21,9 @@ dependencies = [
     "djangorestframework==3.17.2",
     "djangorestframework-stubs==3.17.1",
 ]
+
+[rules]
+missing-type-argument = "ignore"
 ```
 
 ## Serializer `Meta.fields`
@@ -212,3 +219,209 @@ class NotAView:
     queryset = Book.objects.all()
     ordering_fields = ["nope"]
 ```
+
+## View model specialization
+
+drf's bases are generic over the model, but real drf code names it in the class body instead of
+writing the type argument. The model the view's own `queryset` is a queryset of is substituted for
+the `Unknown` the unparameterized base leaves behind.
+
+```py
+from django.db import models
+from rest_framework import generics, viewsets
+
+class Book(models.Model):
+    title = models.CharField(max_length=100)
+
+class Unparameterized(generics.ListAPIView):
+    queryset = Book.objects.all()
+
+class ViewSet(viewsets.ModelViewSet):
+    queryset = Book.objects.all()
+
+def f(view: Unparameterized, viewset: ViewSet) -> None:
+    reveal_type(view.get_queryset())  # revealed: QuerySet[Book, Book]
+    reveal_type(view.get_object())  # revealed: Book
+    reveal_type(viewset.get_queryset())  # revealed: QuerySet[Book, Book]
+    reveal_type(viewset.get_object())  # revealed: Book
+    # the resolved model reaches the queryset's own machinery
+    reveal_type(view.get_queryset().first())  # revealed: Book | None
+    reveal_type(view.get_queryset().values_list("title", flat=True))  # revealed: QuerySet[Book, str]
+```
+
+## An explicit type argument is never contradicted
+
+A view that does write the type argument keeps it: the substitution only ever fills a position that
+carries no information today.
+
+```py
+from django.db import models
+from rest_framework import generics
+
+class Author(models.Model):
+    name = models.CharField(max_length=100)
+
+class Book(models.Model):
+    title = models.CharField(max_length=100)
+
+class Explicit(generics.ListAPIView[Book]):
+    queryset = Book.objects.all()
+
+class Mismatched(generics.ListAPIView[Author]):
+    queryset = Book.objects.all()
+
+def f(explicit: Explicit, mismatched: Mismatched) -> None:
+    reveal_type(explicit.get_queryset())  # revealed: QuerySet[Book, Book]
+    reveal_type(mismatched.get_queryset())  # revealed: QuerySet[Author, Author]
+```
+
+## View serializer specialization
+
+`get_serializer()` builds its result from the `serializer_class` the view names, and
+`get_serializer_class()` returns it.
+
+```py
+from django.db import models
+from rest_framework import generics, serializers
+
+class Book(models.Model):
+    title = models.CharField(max_length=100)
+
+class BookSerializer(serializers.ModelSerializer):
+    class Meta:
+        model = Book
+        fields = ["title"]
+
+class View(generics.ListAPIView):
+    queryset = Book.objects.all()
+    serializer_class = BookSerializer
+
+def f(view: View) -> None:
+    reveal_type(view.get_serializer())  # revealed: BookSerializer
+    reveal_type(view.get_serializer_class())  # revealed: type[BookSerializer]
+    # `many=` sends drf through `ListSerializer` instead, so nothing is claimed
+    reveal_type(view.get_serializer(many=True))  # revealed: BaseSerializer[Unknown]
+    reveal_type(view.get_serializer(**{}))  # revealed: BaseSerializer[Unknown]
+```
+
+## Serializer model specialization
+
+A `ModelSerializer` names its model in `Meta.model`, so `save()`, `create()` and `update()` return
+it. The `Meta` may be inherited.
+
+```py
+from django.db import models
+from rest_framework import serializers
+
+class Book(models.Model):
+    title = models.CharField(max_length=100)
+
+class BookSerializer(serializers.ModelSerializer):
+    class Meta:
+        model = Book
+        fields = ["title"]
+
+class InheritsMeta(BookSerializer): ...
+
+def f(serializer: BookSerializer, inherits: InheritsMeta, book: Book) -> None:
+    reveal_type(serializer.save())  # revealed: Book
+    reveal_type(serializer.create({}))  # revealed: Book
+    reveal_type(serializer.update(book, {}))  # revealed: Book
+    reveal_type(inherits.save())  # revealed: Book
+```
+
+## `many=True` at the constructor
+
+drf builds a `ListSerializer` for `many=True`, whose `save()` returns a list. The stubs describe
+none of that, so a serializer constructed that way reads as one model — exactly as it already does
+when the type argument is written by hand, which is what the two halves of this test show.
+
+```py
+from django.db import models
+from rest_framework import serializers
+
+class Book(models.Model):
+    title = models.CharField(max_length=100)
+
+class Resolved(serializers.ModelSerializer):
+    class Meta:
+        model = Book
+        fields = ["title"]
+
+class Written(serializers.ModelSerializer[Book]):
+    class Meta:
+        model = Book
+        fields = ["title"]
+
+reveal_type(Resolved(data=[], many=True).save())  # revealed: Book
+reveal_type(Written(data=[], many=True).save())  # revealed: Book
+```
+
+## A view's `many=` is visible, so nothing is claimed
+
+The same `many=` reached through the view is an argument of the call, and refuses.
+
+```py
+from django.db import models
+from rest_framework import generics, serializers
+
+class Book(models.Model):
+    title = models.CharField(max_length=100)
+
+class BookSerializer(serializers.ModelSerializer):
+    class Meta:
+        model = Book
+        fields = ["title"]
+
+class View(generics.ListCreateAPIView):
+    queryset = Book.objects.all()
+    serializer_class = BookSerializer
+
+def f(view: View) -> None:
+    reveal_type(view.get_serializer(data=[], many=True).save())  # revealed: Unknown
+```
+
+## Specialization refusals
+
+Nothing is claimed where the class body does not say it plainly: a queryset or serializer built in a
+method, a `Meta` that names no model, a plain `Serializer`, or a project's own override of the
+method — drf reads nothing from the class body to produce that one.
+
+```py
+from django.db import models
+from rest_framework import generics, serializers
+
+class Book(models.Model):
+    title = models.CharField(max_length=100)
+
+class FromMethod(generics.ListAPIView):
+    def get_queryset(self):
+        return Book.objects.all()
+
+class NoMeta(serializers.ModelSerializer): ...
+class PlainSerializer(serializers.Serializer): ...
+
+class BookSerializer(serializers.ModelSerializer):
+    class Meta:
+        model = Book
+        fields = ["title"]
+
+class OverridesSerializerClass(generics.ListAPIView):
+    queryset = Book.objects.all()
+    serializer_class = BookSerializer
+
+    def get_serializer_class(self) -> type[serializers.BaseSerializer]:
+        return BookSerializer
+
+def f(
+    method: FromMethod,
+    no_meta: NoMeta,
+    plain: PlainSerializer,
+    overrides: OverridesSerializerClass,
+) -> None:
+    reveal_type(method.get_queryset())  # revealed: Unknown
+    reveal_type(method.get_object())  # revealed: Unknown
+    reveal_type(no_meta.save())  # revealed: Unknown
+    reveal_type(plain.save())  # revealed: Unknown
+    reveal_type(overrides.get_serializer())  # revealed: BaseSerializer[Unknown]
+```
diff --git a/crates/ty_python_semantic/src/types/call/bind.rs b/crates/ty_python_semantic/src/types/call/bind.rs
index 3536fb2ba6..46703c1e5a 100644
--- a/crates/ty_python_semantic/src/types/call/bind.rs
+++ b/crates/ty_python_semantic/src/types/call/bind.rs
@@ -1961,6 +1961,28 @@ impl<'db> Bindings<'db> {
                         }
                     }
 
+                    // drf's view / serializer methods: substitute the model or
+                    // serializer the receiver's own class body names for the
+                    // `Unknown` an unparameterized drf base left behind
+                    Type::BoundMethod(bound_method)
+                        if django::is_drf_specialized_method(
+                            bound_method.function(db).name(db).as_str(),
+                        ) =>
+                    {
+                        let many_argument = call_arguments.iter().any(|(argument, _)| {
+                            matches!(argument, Argument::Keyword("many") | Argument::Keywords)
+                        });
+                        if let Some(refined) = django::drf_method_return_type(
+                            db,
+                            bound_method.function(db),
+                            bound_method.self_instance(db),
+                            overload.return_ty,
+                            many_argument,
+                        ) {
+                            overload.set_return_type(refined);
+                        }
+                    }
+
                     Type::BoundMethod(bound_method)
                         if let Type::PropertyInstance(property) =
                             bound_method.self_instance(db) =>
diff --git a/crates/ty_python_semantic/src/types/dedicated/django.rs b/crates/ty_python_semantic/src/types/dedicated/django.rs
index 99ba452b1f..7b7e808957 100644
--- a/crates/ty_python_semantic/src/types/dedicated/django.rs
+++ b/crates/ty_python_semantic/src/types/dedicated/django.rs
@@ -11,6 +11,7 @@
 
 use std::borrow::Cow;
 
+use ruff_db::files::File;
 use ruff_db::parsed::ParsedModuleRef;
 use ruff_python_ast as ast;
 use ruff_python_ast::name::Name;
@@ -21,6 +22,7 @@ use ty_python_core::{global_scope, place_table, use_def_map};
 
 use crate::place::{Place, known_module_symbol};
 use crate::types::class::{CodeGeneratorKind, Field, FieldKind};
+use crate::types::function::FunctionType;
 use crate::types::list_members::all_end_of_scope_members;
 use crate::types::member::class_member;
 use crate::types::signatures::{Parameter, Parameters, Signature};
@@ -83,6 +85,35 @@ fn is_drf_generic_view(db: &dyn Db, class: StaticClassLiteral<'_>) -> bool {
     has_base_named(db, class, "rest_framework.generics", "GenericAPIView")
 }
 
+/// the single type `class`'s own body binds `name` to
+///
+/// the binding is read out of the place table rather than by member lookup,
+/// deliberately: resolving it as a member would infer the very scope these
+/// queries run from. `None` when the body doesn't bind `name`, or binds it
+/// more than one way
+fn own_body_binding<'db>(
+    db: &'db dyn Db,
+    class: StaticClassLiteral<'db>,
+    name: &str,
+) -> Option<Type<'db>> {
+    let body_scope = class.body_scope(db);
+    let symbol = place_table(db, body_scope).symbol_id(name)?;
+    let use_def = use_def_map(db, body_scope);
+    let mut bound = None;
+    for binding in use_def.end_of_scope_symbol_bindings(symbol) {
+        let DefinitionState::Defined(definition) = binding.binding else {
+            continue;
+        };
+        let candidate = binding_type(db, definition);
+        // more than one binding only agrees if they say the same thing
+        if bound.is_some_and(|bound| bound != candidate) {
+            return None;
+        }
+        bound = Some(candidate);
+    }
+    bound
+}
+
 /// the model a drf view's filter-backend field lists resolve against: the
 /// model its own `queryset` is a queryset of. `None` for anything else —
 /// a view that builds its queryset in `get_queryset`, or inherits it, leaves
@@ -96,24 +127,7 @@ pub(in crate::types) fn drf_view_model<'db>(
     if !is_drf_generic_view(db, class) {
         return None;
     }
-    // read the sibling `queryset` binding straight out of the class body:
-    // resolving it as a member would infer the very scope this runs from
-    let body_scope = class.body_scope(db);
-    let symbol = place_table(db, body_scope).symbol_id("queryset")?;
-    let use_def = use_def_map(db, body_scope);
-    let mut model = None;
-    for binding in use_def.end_of_scope_symbol_bindings(symbol) {
-        let DefinitionState::Defined(definition) = binding.binding else {
-            continue;
-        };
-        let candidate = queryset_or_manager_model(db, binding_type(db, definition))?;
-        // more than one binding only agrees if they name the same model
-        if model.is_some_and(|model| model != candidate) {
-            return None;
-        }
-        model = Some(candidate);
-    }
-    model
+    queryset_or_manager_model(db, own_body_binding(db, class, "queryset")?)
 }
 
 /// the specialized instance type constructed by a django field constructor
@@ -1060,24 +1074,10 @@ pub(in crate::types) fn meta_model<'db>(
     db: &'db dyn Db,
     meta: StaticClassLiteral<'db>,
 ) -> Option<StaticClassLiteral<'db>> {
-    let body_scope = meta.body_scope(db);
-    let symbol = place_table(db, body_scope).symbol_id("model")?;
-    let use_def = use_def_map(db, body_scope);
-    let mut model = None;
-    for binding in use_def.end_of_scope_symbol_bindings(symbol) {
-        let DefinitionState::Defined(definition) = binding.binding else {
-            continue;
-        };
-        let candidate = binding_type(db, definition)
-            .as_class_literal()
-            .and_then(ClassLiteral::as_static)
-            .filter(|candidate| is_model(db, *candidate))?;
-        if model.is_some_and(|model| model != candidate) {
-            return None;
-        }
-        model = Some(candidate);
-    }
-    model
+    own_body_binding(db, meta, "model")?
+        .as_class_literal()
+        .and_then(ClassLiteral::as_static)
+        .filter(|candidate| is_model(db, *candidate))
 }
 
 /// a class-body attribute whose value is a list of model field paths
@@ -1272,6 +1272,193 @@ pub(in crate::types) fn with_queryset_row<'db>(
     Some(Type::instance(db, class_type))
 }
 
+// ---------------------------------------------------------------------------
+// drf view / serializer specialization
+//
+// `djangorestframework-stubs` declares the drf bases generic over the model
+// (`GenericAPIView[_MT_co]`, `ModelSerializer[_MT]`), but real drf code never
+// writes that type argument: the class body names the model instead, in
+// `queryset` or `Meta.model`, and drf's own machinery reads it from there. an
+// unparameterized base leaves every one of those type parameters `Unknown`, so
+// `get_queryset()` is a `QuerySet[Unknown, Unknown]` and `save()` is `Unknown`
+// however plainly the body says otherwise. this substitutes the model the body
+// names back into exactly those positions, which is what writing the type
+// argument by hand already achieves today
+// ---------------------------------------------------------------------------
+
+/// whether `file` belongs to the `rest_framework` package
+fn is_drf_module(db: &dyn Db, file: File) -> bool {
+    file_to_module(db, file).is_some_and(|module| {
+        let name = module.name(db).as_str();
+        name == "rest_framework" || name.starts_with("rest_framework.")
+    })
+}
+
+/// the model a drf `ModelSerializer` serializes: the one its nested `Meta`
+/// names. the `Meta` is the first on the mro, drf's own `ModelSerializer.Meta`
+/// included — reaching that one means the serializer declares none of its own,
+/// and it declares `model` as an annotation with no value, so it resolves to
+/// nothing
+#[salsa::tracked(returns(copy), heap_size=ruff_memory_usage::heap_size)]
+fn drf_serializer_model<'db>(
+    db: &'db dyn Db,
+    class: StaticClassLiteral<'db>,
+) -> Option<StaticClassLiteral<'db>> {
+    if !has_base_named(db, class, "rest_framework.serializers", "ModelSerializer") {
+        return None;
+    }
+    let meta = class
+        .iter_mro(db, None)
+        .filter_map(ClassBase::into_class)
+        .filter_map(|base| base.class_literal(db).as_static())
+        .find_map(|base| own_body_binding(db, base, "Meta"))?
+        .as_class_literal()
+        .and_then(ClassLiteral::as_static)?;
+    meta_model(db, meta)
+}
+
+/// the serializer class a drf view's own `serializer_class` names. `None` when
+/// there is none, or it doesn't resolve to a serializer
+#[salsa::tracked(returns(copy), heap_size=ruff_memory_usage::heap_size)]
+fn drf_view_serializer<'db>(
+    db: &'db dyn Db,
+    class: StaticClassLiteral<'db>,
+) -> Option<StaticClassLiteral<'db>> {
+    if !is_drf_generic_view(db, class) {
+        return None;
+    }
+    own_body_binding(db, class, "serializer_class")?
+        .as_class_literal()
+        .and_then(ClassLiteral::as_static)
+        .filter(|candidate| {
+            has_base_named(
+                db,
+                *candidate,
+                "rest_framework.serializers",
+                "BaseSerializer",
+            )
+        })
+}
+
+/// whether a class outside drf in `class`'s mro declares `name` itself — a
+/// project's own override of a method drf's own machinery dispatches through
+fn declares_outside_drf<'db>(db: &'db dyn Db, class: StaticClassLiteral<'db>, name: &str) -> bool {
+    class
+        .iter_mro(db, None)
+        .filter_map(ClassBase::into_class)
+        .filter_map(|candidate| candidate.class_literal(db).as_static())
+        .filter(|candidate| !is_drf_module(db, candidate.file(db)))
+        .any(|candidate| {
+            place_table(db, candidate.body_scope(db))
+                .symbol_id(name)
+                .is_some()
+        })
+}
+
+/// substitute `model`'s instance type for the `Unknown` an unparameterized drf
+/// base left in `declared_return`: either the type parameter itself (`_MT`) or
+/// a generic alias every argument of which is one (`QuerySet[_MT_co, _Row]`,
+/// whose `_Row` defaults to `_MT_co`)
+///
+/// requiring *every* argument to be dynamic is what keeps this monotonic: it
+/// fires only where today's answer carries no information at all
+fn substitute_model<'db>(
+    db: &'db dyn Db,
+    declared_return: Type<'db>,
+    model: StaticClassLiteral<'db>,
+) -> Option<Type<'db>> {
+    let model_instance = Type::instance(db, model.default_specialization(db));
+    if declared_return.is_dynamic() {
+        return Some(model_instance);
+    }
+    let ClassType::Generic(alias) = declared_return.nominal_class(db)? else {
+        return None;
+    };
+    let arity = alias.specialization(db).types(db).len();
+    if !alias
+        .specialization(db)
+        .types(db)
+        .iter()
+        .all(Type::is_dynamic)
+    {
+        return None;
+    }
+    let class_type = alias
+        .origin(db)
+        .apply_specialization(db, |generic_context| {
+            generic_context.specialize(db, Cow::Owned(vec![model_instance; arity]))
+        });
+    Some(Type::instance(db, class_type))
+}
+
+/// the more precise return type a drf method has once the receiver's class
+/// body is read, or `None` to keep the stub's own
+///
+/// `many_argument` reports a call that may be routing through drf's
+/// `ListSerializer` — `many=` names it, and a `**kwargs` splat may hide it.
+/// the result is then a list serializer rather than the serializer class
+pub(in crate::types) fn drf_method_return_type<'db>(
+    db: &'db dyn Db,
+    method: FunctionType<'db>,
+    self_instance: Type<'db>,
+    declared_return: Type<'db>,
+    many_argument: bool,
+) -> Option<Type<'db>> {
+    // only drf's own declarations: a project's override of `get_queryset` is
+    // its own function returning whatever its own body returns, and drf reads
+    // nothing from the class body to produce it
+    if !is_drf_module(db, method.file(db)) {
+        return None;
+    }
+    let class = instance_static_class(db, self_instance)?;
+    let name = method.name(db).as_str();
+    let refined = match name {
+        "get_queryset" | "get_object" => {
+            substitute_model(db, declared_return, drf_view_model(db, class)?)?
+        }
+        "get_serializer" | "get_serializer_class" => {
+            // `get_serializer` builds its result by calling
+            // `get_serializer_class()`, so an override of that is free to
+            // ignore `serializer_class` entirely
+            if many_argument || declares_outside_drf(db, class, "get_serializer_class") {
+                return None;
+            }
+            let serializer = Type::instance(
+                db,
+                drf_view_serializer(db, class)?.default_specialization(db),
+            );
+            if name == "get_serializer" {
+                serializer
+            } else {
+                serializer.to_meta_type(db)
+            }
+        }
+        "save" | "create" | "update" => {
+            substitute_model(db, declared_return, drf_serializer_model(db, class)?)?
+        }
+        _ => return None,
+    };
+    // never contradict a view or serializer that *did* write its type argument
+    refined
+        .is_assignable_to(db, declared_return)
+        .then_some(refined)
+}
+
+/// the drf methods [`drf_method_return_type`] can refine, for the call site to
+/// reject the overwhelming majority of calls before asking
+pub(in crate::types) fn is_drf_specialized_method(name: &str) -> bool {
+    matches!(
+        name,
+        "get_queryset"
+            | "get_object"
+            | "get_serializer"
+            | "get_serializer_class"
+            | "save"
+            | "create"
+            | "update"
+    )
+}
+
 /// the methods django marks `alters_data = True`
 ///
 /// django's template variable resolution refuses to call one of these and
diff --git a/docs/basedpython/frameworks/django.md b/docs/basedpython/frameworks/django.md
index d74b4c32ec..2446469e55 100644
--- a/docs/basedpython/frameworks/django.md
+++ b/docs/basedpython/frameworks/django.md
@@ -37,6 +37,28 @@ nothing is reported unless the model is certain. a serializer without a `Meta.mo
 
 `source="author.name"` on a serializer field is deliberately **not** checked: drf resolves it with `getattr` at serialization time against whatever object it is handed, which is routinely an annotated row or a dict rather than an instance of `Meta.model`
 
+### drf view and serializer specialization
+
+`djangorestframework-stubs` declares the drf bases generic over the model, but real drf code names the model in the class body rather than writing `ListAPIView[Book]`. the model the class body names is substituted for the type argument nobody writes:
+
+- a view's `get_queryset()` and `get_object()`, from the model its own `queryset` is a queryset of
+- a view's `get_serializer()` and `get_serializer_class()`, from the `serializer_class` it names
+- a `ModelSerializer`'s `save()`, `create()` and `update()`, from `Meta.model`
+
+```by
+class BookViewSet(viewsets.ModelViewSet):
+    queryset = Book.objects.all()
+    serializer_class = BookSerializer
+
+view.get_queryset()      # QuerySet[Book, Book], was QuerySet[Unknown, Unknown]
+view.get_serializer()    # BookSerializer, was BaseSerializer[Unknown]
+serializer.save()        # Book, was Unknown
+```
+
+a view or serializer that *does* write its type argument keeps it — the substitution only fills a position that carries no information today. anything the class body does not say plainly is left alone: a queryset built in `get_queryset`, a `serializer_class` chosen in `get_serializer_class`, a serializer with no `Meta.model`, and your own override of any of these methods
+
+`.data` and `.validated_data` stay `Any` on purpose — see below
+
 ### transpilation compatibility
 
 - `optional?.chaining` works across nullable relations: `author?.birthday?.year`
@@ -82,6 +104,29 @@ class Author(models.Model):
 
 models created dynamically (e.g., via `type()` or factories) don't check. stick to class definitions.
 
+### drf `many=True` at the constructor
+
+`BookSerializer(data=[...], many=True)` builds a `ListSerializer` at runtime, so its `save()` returns a *list* of models. the stubs describe none of that — `many` is an ordinary `bool` parameter and the constructed type is the serializer class either way — so `save()` reads as one model:
+
+```by
+for book in BookSerializer(data=payload, many=True).save():  # `Book` is not iterable
+```
+
+writing `ModelSerializer[Book]` by hand has always read the same way; the model resolved from `Meta.model` just makes it read that way without the annotation. going through the view (`self.get_serializer(data=payload, many=True)`) is not affected — a `many=` argument there is visible, so nothing is claimed about the result
+
+### drf `.data` and `.validated_data`
+
+both stay `Any`. their key sets look like they follow from `Meta.fields`, and they don't:
+
+- `validate()` may add, drop or rename any key, and returning a rewritten dict is the documented way to do cross-field validation
+- `save(**kwargs)` merges its keywords into what `create()` receives
+- `to_representation()` may add keys to `.data`
+- a key is a field's `source`, not its name, and a dotted `source="author.name"` restructures the dict entirely
+- `.data` on a serializer built from `data=` holds only the validated subset, while `.data` on one built from an instance holds every field
+- `many=True` makes both a list
+
+a `TypedDict` is closed, so every one of these turns correct code into an error. `Any` reports nothing, which is the right answer here
+
 ### querysets from `values()` and `annotate()`
 
 the return types of `values()`, `values_list()`, and `annotate()` aren't fully precise — they check at the generic level but don't know the specific fields returned.

From 32c3b2d096f0e68289a686465254fcb2398f955a Mon Sep 17 00:00:00 2001
From: KotlinIsland <65446343+kotlinisland@users.noreply.github.com>
Date: Sat, 8 Aug 2026 21:38:32 +1000
Subject: [PATCH 11/16] celery's task signatures already survive, with the
 stubs installed

the case for building `.delay` typing was measured without `celery-types`, the
package typed celery projects actually install. with it, `@shared_task` gives
`Task[(book_id: int, force: bool = False), str]` and all four of the wrong calls
that motivated the work already report

so there is nothing to build, and these tests pin that rather than reimplement it.
they also record the one place celery-types refuses: `Celery` is generic over the
task *class*, so `@app.task` widens to `Task[(...), Any]`
---
 .../resources/mdtest/external/celery.lock     | 234 ++++++++++++++++++
 .../resources/mdtest/external/celery.md       | 185 ++++++++++++++
 2 files changed, 419 insertions(+)
 create mode 100644 crates/ty_python_semantic/resources/mdtest/external/celery.lock
 create mode 100644 crates/ty_python_semantic/resources/mdtest/external/celery.md

diff --git a/crates/ty_python_semantic/resources/mdtest/external/celery.lock b/crates/ty_python_semantic/resources/mdtest/external/celery.lock
new file mode 100644
index 0000000000..7cd3661139
--- /dev/null
+++ b/crates/ty_python_semantic/resources/mdtest/external/celery.lock
@@ -0,0 +1,234 @@
+version = 1
+revision = 3
+requires-python = "==3.13.*"
+
+[[package]]
+name = "amqp"
+version = "5.3.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "vine" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/79/fc/ec94a357dfc6683d8c86f8b4cfa5416a4c36b28052ec8260c77aca96a443/amqp-5.3.1.tar.gz", hash = "sha256:cddc00c725449522023bad949f70fff7b48f0b1ade74d170a6f10ab044739432", size = 129013, upload-time = "2024-11-12T19:55:44.051Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/26/99/fc813cd978842c26c82534010ea849eee9ab3a13ea2b74e95cb9c99e747b/amqp-5.3.1-py3-none-any.whl", hash = "sha256:43b3319e1b4e7d1251833a93d672b4af1e40f3d632d479b98661a95f117880a2", size = 50944, upload-time = "2024-11-12T19:55:41.782Z" },
+]
+
+[[package]]
+name = "billiard"
+version = "4.2.4"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/58/23/b12ac0bcdfb7360d664f40a00b1bda139cbbbced012c34e375506dbd0143/billiard-4.2.4.tar.gz", hash = "sha256:55f542c371209e03cd5862299b74e52e4fbcba8250ba611ad94276b369b6a85f", size = 156537, upload-time = "2025-11-30T13:28:48.52Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/cb/87/8bab77b323f16d67be364031220069f79159117dd5e43eeb4be2fef1ac9b/billiard-4.2.4-py3-none-any.whl", hash = "sha256:525b42bdec68d2b983347ac312f892db930858495db601b5836ac24e6477cde5", size = 87070, upload-time = "2025-11-30T13:28:47.016Z" },
+]
+
+[[package]]
+name = "celery"
+version = "5.6.3"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "billiard" },
+    { name = "click" },
+    { name = "click-didyoumean" },
+    { name = "click-plugins" },
+    { name = "click-repl" },
+    { name = "kombu" },
+    { name = "python-dateutil" },
+    { name = "tzlocal" },
+    { name = "vine" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/e8/b4/a1233943ab5c8ea05fb877a88a0a0622bf47444b99e4991a8045ac37ea1d/celery-5.6.3.tar.gz", hash = "sha256:177006bd2054b882e9f01be59abd8529e88879ef50d7918a7050c5a9f4e12912", size = 1742243, upload-time = "2026-03-26T12:14:51.76Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/cf/c9/6eccdda96e098f7ae843162db2d3c149c6931a24fda69fe4ab84d0027eb5/celery-5.6.3-py3-none-any.whl", hash = "sha256:0808f42f80909c4d5833202360ffafb2a4f83f4d8e23e1285d926610e9a7afa6", size = 451235, upload-time = "2026-03-26T12:14:49.491Z" },
+]
+
+[[package]]
+name = "celery-types"
+version = "0.26.0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "typing-extensions" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/fc/38/813dd7534e41682684d3a5c2cc4a8710e3acc51b364920b9c4d747c7b18f/celery_types-0.26.0.tar.gz", hash = "sha256:fa318136fdad83f83f1531deecd9fe664b5dfffff29f3c31e9120a46b8e3908f", size = 106210, upload-time = "2026-03-12T23:06:49.941Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/d9/e5/c5ec98f7fd7817d077c9a5a5e705d54f74d4ca08ee3f14dee881c93c0511/celery_types-0.26.0-py3-none-any.whl", hash = "sha256:eb9da76f461786091970df466ec647d9a27956399852542cb6cab9309970f950", size = 211260, upload-time = "2026-03-12T23:06:48.588Z" },
+]
+
+[[package]]
+name = "click"
+version = "8.4.2"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "colorama", marker = "sys_platform == 'win32'" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/76/d4/81420972a676e8ffea40450d8c8c92943e7218a78fe9b64359836cc9876b/click-8.4.2.tar.gz", hash = "sha256:9a6cea6e60b17ebe0a44c5cc636d94f09bd66142c1cd7d8b4cd731c4917a15f6", size = 338000, upload-time = "2026-06-24T17:45:15.148Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/fb/e2/79c688af8b210d232694e31e59da9f6ec747bae31c3f5946e4e9b98860d5/click-8.4.2-py3-none-any.whl", hash = "sha256:e6f9f66136c816745b9d65817da91d61d957fb16e02e4dcd0552553c5a197b76", size = 119243, upload-time = "2026-06-24T17:45:13.73Z" },
+]
+
+[[package]]
+name = "click-didyoumean"
+version = "0.3.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "click" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/30/ce/217289b77c590ea1e7c24242d9ddd6e249e52c795ff10fac2c50062c48cb/click_didyoumean-0.3.1.tar.gz", hash = "sha256:4f82fdff0dbe64ef8ab2279bd6aa3f6a99c3b28c05aa09cbfc07c9d7fbb5a463", size = 3089, upload-time = "2024-03-24T08:22:07.499Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/1b/5b/974430b5ffdb7a4f1941d13d83c64a0395114503cc357c6b9ae4ce5047ed/click_didyoumean-0.3.1-py3-none-any.whl", hash = "sha256:5c4bb6007cfea5f2fd6583a2fb6701a22a41eb98957e63d0fac41c10e7c3117c", size = 3631, upload-time = "2024-03-24T08:22:06.356Z" },
+]
+
+[[package]]
+name = "click-plugins"
+version = "1.1.1.2"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "click" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/c3/a4/34847b59150da33690a36da3681d6bbc2ec14ee9a846bc30a6746e5984e4/click_plugins-1.1.1.2.tar.gz", hash = "sha256:d7af3984a99d243c131aa1a828331e7630f4a88a9741fd05c927b204bcf92261", size = 8343, upload-time = "2025-06-25T00:47:37.555Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/3d/9a/2abecb28ae875e39c8cad711eb1186d8d14eab564705325e77e4e6ab9ae5/click_plugins-1.1.1.2-py2.py3-none-any.whl", hash = "sha256:008d65743833ffc1f5417bf0e78e8d2c23aab04d9745ba817bd3e71b0feb6aa6", size = 11051, upload-time = "2025-06-25T00:47:36.731Z" },
+]
+
+[[package]]
+name = "click-repl"
+version = "0.3.0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "click" },
+    { name = "prompt-toolkit" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/cb/a2/57f4ac79838cfae6912f997b4d1a64a858fb0c86d7fcaae6f7b58d267fca/click-repl-0.3.0.tar.gz", hash = "sha256:17849c23dba3d667247dc4defe1757fff98694e90fe37474f3feebb69ced26a9", size = 10449, upload-time = "2023-06-15T12:43:51.141Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/52/40/9d857001228658f0d59e97ebd4c346fe73e138c6de1bce61dc568a57c7f8/click_repl-0.3.0-py3-none-any.whl", hash = "sha256:fb7e06deb8da8de86180a33a9da97ac316751c094c6899382da7feeeeb51b812", size = 10289, upload-time = "2023-06-15T12:43:48.626Z" },
+]
+
+[[package]]
+name = "colorama"
+version = "0.4.6"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/d8/53/6f443c9a4a8358a93a6792e2acffb9d9d5cb0a5cfd8802644b7b1c9a02e4/colorama-0.4.6.tar.gz", hash = "sha256:08695f5cb7ed6e0531a20572697297273c47b8cae5a63ffc6d6ed5c201be6e44", size = 27697, upload-time = "2022-10-25T02:36:22.414Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/d1/d6/3965ed04c63042e047cb6a3e6ed1a63a35087b6a609aa3a15ed8ac56c221/colorama-0.4.6-py2.py3-none-any.whl", hash = "sha256:4f1d9991f5acc0ca119f9d443620b77f9d6b33703e51011c16baf57afb285fc6", size = 25335, upload-time = "2022-10-25T02:36:20.889Z" },
+]
+
+[[package]]
+name = "kombu"
+version = "5.6.2"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "amqp" },
+    { name = "packaging" },
+    { name = "tzdata" },
+    { name = "vine" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/b6/a5/607e533ed6c83ae1a696969b8e1c137dfebd5759a2e9682e26ff1b97740b/kombu-5.6.2.tar.gz", hash = "sha256:8060497058066c6f5aed7c26d7cd0d3b574990b09de842a8c5aaed0b92cc5a55", size = 472594, upload-time = "2025-12-29T20:30:07.779Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/fb/0f/834427d8c03ff1d7e867d3db3d176470c64871753252b21b4f4897d1fa45/kombu-5.6.2-py3-none-any.whl", hash = "sha256:efcfc559da324d41d61ca311b0c64965ea35b4c55cc04ee36e55386145dace93", size = 214219, upload-time = "2025-12-29T20:30:05.74Z" },
+]
+
+[[package]]
+name = "mdtest-deps"
+version = "0.1.0"
+source = { virtual = "." }
+dependencies = [
+    { name = "celery" },
+    { name = "celery-types" },
+]
+
+[package.metadata]
+requires-dist = [
+    { name = "celery", specifier = "==5.6.3" },
+    { name = "celery-types", specifier = "==0.26.0" },
+]
+
+[[package]]
+name = "packaging"
+version = "26.3"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/7d/fa/3944b40b07da9ce895c0e6303a5ab7d53da063554f534556b134a54d6093/packaging-26.3.tar.gz", hash = "sha256:94edc256424af38762eb31306eed28beb9f0efc50a8837492c9d6fd6004aed79", size = 313412, upload-time = "2026-08-04T18:15:28.737Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/63/34/ba1c580383c9eada3711951fef0795c80b829a078d72188184bcab9dd527/packaging-26.3-py3-none-any.whl", hash = "sha256:d7193f7c8e4e93f444fde0262bf90af30e16fa0ad0ad44cb553c87339b23cd1c", size = 129956, upload-time = "2026-08-04T18:15:27.159Z" },
+]
+
+[[package]]
+name = "prompt-toolkit"
+version = "3.0.53"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "wcwidth" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/7d/ea/39b988c938f75cb75d7045b5c69f8bfed47ee2152c8837fb403de29d6fb8/prompt_toolkit-3.0.53.tar.gz", hash = "sha256:9ec8a0ad96d5c56148b3f914aa79c1564c3fde5d2e6b876e7bc327e353cf8fa6", size = 435492, upload-time = "2026-07-26T20:56:14.758Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/54/6f/84908cad2d6aa5144abcf7b42709fe4fdb459bc640ec7ac5786e7693dabc/prompt_toolkit-3.0.53-py3-none-any.whl", hash = "sha256:01c0891d7f9237d5e339f7d3e42cdae80b7534abb1c7c0e3352efba6231492f2", size = 392288, upload-time = "2026-07-26T20:56:12.512Z" },
+]
+
+[[package]]
+name = "python-dateutil"
+version = "2.9.0.post0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "six" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/66/c0/0c8b6ad9f17a802ee498c46e004a0eb49bc148f2fd230864601a86dcf6db/python-dateutil-2.9.0.post0.tar.gz", hash = "sha256:37dd54208da7e1cd875388217d5e00ebd4179249f90fb72437e91a35459a0ad3", size = 342432, upload-time = "2024-03-01T18:36:20.211Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/ec/57/56b9bcc3c9c6a792fcbaf139543cee77261f3651ca9da0c93f5c1221264b/python_dateutil-2.9.0.post0-py2.py3-none-any.whl", hash = "sha256:a8b2bc7bffae282281c8140a97d3aa9c14da0b136dfe83f850eea9a5f7470427", size = 229892, upload-time = "2024-03-01T18:36:18.57Z" },
+]
+
+[[package]]
+name = "six"
+version = "1.17.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/94/e7/b2c673351809dca68a0e064b6af791aa332cf192da575fd474ed7d6f16a2/six-1.17.0.tar.gz", hash = "sha256:ff70335d468e7eb6ec65b95b99d3a2836546063f63acc5171de367e834932a81", size = 34031, upload-time = "2024-12-04T17:35:28.174Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/b7/ce/149a00dd41f10bc29e5921b496af8b574d8413afcd5e30dfa0ed46c2cc5e/six-1.17.0-py2.py3-none-any.whl", hash = "sha256:4721f391ed90541fddacab5acf947aa0d3dc7d27b2e1e8eda2be8970586c3274", size = 11050, upload-time = "2024-12-04T17:35:26.475Z" },
+]
+
+[[package]]
+name = "typing-extensions"
+version = "4.16.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/f6/cc/6253133b5bb138fc3306cebfbda2c520f545d36b5be2c7255cc528bb45d6/typing_extensions-4.16.0.tar.gz", hash = "sha256:dc983d19a509c94dba722ee6abd33940f7c05a89e243c47e907eb4db6f1a43e5", size = 113555, upload-time = "2026-07-02T08:40:05.92Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/49/d3/b8441a820a491ddfc024b0b0cf0393375b75ea13866d9c66727e54c2fc80/typing_extensions-4.16.0-py3-none-any.whl", hash = "sha256:481caa481374e813c1b176ada14e97f1f67a4539ce9cfeb3f350d78d6370c2e8", size = 45571, upload-time = "2026-07-02T08:40:04.659Z" },
+]
+
+[[package]]
+name = "tzdata"
+version = "2026.3"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/92/ff/5a28bdfd8c3ebec42564ac7d0e54ca3db65044a9314a97f9564fa7a1e926/tzdata-2026.3.tar.gz", hash = "sha256:4a1518b8993086a7982523e071643f3c0e5f213e75b21318e78bcabfff9d1415", size = 198674, upload-time = "2026-07-10T08:50:37.887Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/e5/6d/b53b99a9f2766d095985947a5782f1702cabb129a34f7a802d7197af832f/tzdata-2026.3-py2.py3-none-any.whl", hash = "sha256:dc096730c87af6cab1b171c9d532be840741ff5d459015e7f6947bd7d7e54931", size = 348168, upload-time = "2026-07-10T08:50:36.46Z" },
+]
+
+[[package]]
+name = "tzlocal"
+version = "5.4.4"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "tzdata", marker = "sys_platform == 'win32'" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/81/5b/879b2f932adfa7a053c360d50bc896c977fa6426109185f7c12ebdd0cb9d/tzlocal-5.4.4.tar.gz", hash = "sha256:8dbb8660838688a7b6ba4fed31d18dedf842afb4d47ca050d6d891c2c15f3be4", size = 31170, upload-time = "2026-06-29T08:03:40.026Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/9e/a4/017a7a6cbe387d961a688ec31364ae60a5c4e22c96ae9921b79a947c855d/tzlocal-5.4.4-py3-none-any.whl", hash = "sha256:aae09f0126a8a86fa736be266eb4a471380d26a0de3bc14844e7821fee3e2a15", size = 18115, upload-time = "2026-06-29T08:03:38.666Z" },
+]
+
+[[package]]
+name = "vine"
+version = "5.1.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/bd/e4/d07b5f29d283596b9727dd5275ccbceb63c44a1a82aa9e4bfd20426762ac/vine-5.1.0.tar.gz", hash = "sha256:8b62e981d35c41049211cf62a0a1242d8c1ee9bd15bb196ce38aefd6799e61e0", size = 48980, upload-time = "2023-11-05T08:46:53.857Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/03/ff/7c0c86c43b3cbb927e0ccc0255cb4057ceba4799cd44ae95174ce8e8b5b2/vine-5.1.0-py3-none-any.whl", hash = "sha256:40fdf3c48b2cfe1c38a49e9ae2da6fda88e4794c810050a728bd7413811fb1dc", size = 9636, upload-time = "2023-11-05T08:46:51.205Z" },
+]
+
+[[package]]
+name = "wcwidth"
+version = "0.8.2"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/34/74/c6428f875774288bec1396f5bfcbc2d925700a4dad61727fd5f2b12f249d/wcwidth-0.8.2.tar.gz", hash = "sha256:91fbef97204b96a3d4d421609b80340b760cf33e26da123ff243d76b1fda8dda", size = 1466253, upload-time = "2026-06-29T18:11:11.601Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/96/42/3e5985a0a7e57de470b320c6d6a1a67c844f6737a587f3d44dd13d1819e7/wcwidth-0.8.2-py3-none-any.whl", hash = "sha256:d63947694a0539a1d51e01eda7caf800c291020e6cdd7e28ad7b14dd33ad4f85", size = 323166, upload-time = "2026-06-29T18:11:09.888Z" },
+]
diff --git a/crates/ty_python_semantic/resources/mdtest/external/celery.md b/crates/ty_python_semantic/resources/mdtest/external/celery.md
new file mode 100644
index 0000000000..15dd676003
--- /dev/null
+++ b/crates/ty_python_semantic/resources/mdtest/external/celery.md
@@ -0,0 +1,185 @@
+# Celery
+
+celery ships no `py.typed`, and `shared_task` is `def shared_task(*args, **kwargs)` in the source,
+so without stubs a decorated task is `Unknown` and every `.delay()` call goes unchecked. The
+`celery-types` package supplies `Task[_P, _R]` — the same whole-callable capture the vendored
+`functools.byi` uses for `_lru_cache_wrapper` — and `delay` re-exposes the task function's own
+parameters. These tests pin that recovery, because it is what makes a mistyped or miscounted
+`.delay()` argument an error rather than silence.
+
+```toml
+[environment]
+python-version = "3.13"
+python-platform = "linux"
+
+[project]
+dependencies = ["celery==5.6.3", "celery-types==0.26.0"]
+```
+
+## A bare `@shared_task` keeps its signature
+
+`.delay` takes exactly what the task function takes, and the result carries the return type.
+
+```py
+from celery import shared_task
+
+@shared_task
+def process(book_id: int, force: bool = False) -> str:
+    return f"{book_id}{force}"
+
+reveal_type(process)  # revealed: Task[(book_id: int, force: bool = False), str]
+reveal_type(process.delay(1))  # revealed: AsyncResult[str]
+reveal_type(process.delay(1).get())  # revealed: str
+
+process.delay(1, True)
+process.delay(1, force=True)
+
+# error: [invalid-argument-type] "Argument to bound method `Task.delay` is incorrect: Expected `int`, found `Literal["not an int"]`"
+process.delay("not an int")
+
+# error: [missing-argument] "No argument provided for required parameter `book_id` of bound method `Task.delay`"
+process.delay()
+
+# error: [invalid-argument-type]
+# error: [too-many-positional-arguments]
+process.delay(1, 2, 3, 4)
+
+# error: [unknown-argument] "Argument `nope` does not match any known parameter of bound method `Task.delay`"
+process.delay(1, nope=True)
+```
+
+## `@shared_task(...)` with arguments keeps its signature
+
+The called form resolves through a different overload, so it is worth pinning separately.
+
+```py
+from celery import shared_task
+
+@shared_task(name="x", rate_limit="10/m")
+def named(a: int) -> bytes:
+    return b""
+
+reveal_type(named)  # revealed: Task[(a: int), bytes]
+reveal_type(named.delay(1))  # revealed: AsyncResult[bytes]
+
+# error: [invalid-argument-type]
+named.delay("nope")
+```
+
+## `bind=True` does not leak `self` into `.delay`
+
+celery prepends the task instance to the task function, and callers must not pass it. Confirmed
+against celery 5.6.3: `inspect.signature(bound.run)` is `(a: int) -> str`, with no `self`.
+
+```py
+from celery import shared_task
+
+@shared_task(bind=True, max_retries=5)
+def flaky(self, url: str, attempts: int = 3) -> bytes:
+    return url.encode()
+
+reveal_type(flaky)  # revealed: Task[(url: str, attempts: int = 3), bytes]
+reveal_type(flaky.delay("http://x"))  # revealed: AsyncResult[bytes]
+
+flaky.delay("http://x", 1)
+
+# passing the task instance explicitly is the mistake `bind=True` invites
+# error: [invalid-argument-type]
+# error: [invalid-argument-type]
+flaky.delay(flaky, "http://x")
+```
+
+## Calling a task directly still runs it synchronously
+
+A task is callable, and that path keeps the function's own return type.
+
+```py
+from celery import shared_task
+
+@shared_task
+def add(x: int, y: int) -> int:
+    return x + y
+
+reveal_type(add(1, 2))  # revealed: int
+
+# error: [invalid-argument-type]
+add("a", 2)
+```
+
+## The rest of a task's surface survives
+
+`apply_async` takes a packed tuple and dict rather than the parameters spread, so its arguments stay
+`Any`; the result type is still recovered. `si` is parameter-checked, `s` is not — it is used for
+partial application in a chain.
+
+```py
+from celery import shared_task
+
+@shared_task
+def add(x: int, y: int) -> int:
+    return x + y
+
+reveal_type(add.apply_async((1, 2)))  # revealed: AsyncResult[int]
+reveal_type(add.apply_async(args=(1, 2), countdown=10))  # revealed: AsyncResult[int]
+reveal_type(add.s(1))  # revealed: Signature[int]
+reveal_type(add.si(1, 2))  # revealed: Signature[int]
+reveal_type(add.name)  # revealed: str
+reveal_type(add.request)  # revealed: Context
+reveal_type(add.max_retries)  # revealed: int | None
+
+# `si` is spread, so it is checked
+# error: [invalid-argument-type]
+add.si("a", 2)
+```
+
+## A task imported from another module keeps its signature
+
+`tasks.py`:
+
+```py
+from celery import shared_task
+
+@shared_task
+def add(x: int, y: int) -> int:
+    return x + y
+```
+
+`consumer.py`:
+
+```py
+from tasks import add
+
+reveal_type(add)  # revealed: Task[(x: int, y: int), int]
+
+# error: [invalid-argument-type]
+add.delay("a", 2)
+```
+
+## `@app.task` refuses rather than guesses
+
+`Celery` is generic over the task *class* so that `task_cls=` and `base=` work, and `celery-types`
+declares `Celery.task` as returning that same class variable. It therefore cannot also carry the
+task function's parameters, and `app.task` widens to `Task[(...), Any]`. That is a refusal, not a
+wrong answer: the calls below are unchecked, exactly as they are without stubs, and nothing correct
+is rejected.
+
+```py
+from celery import Celery
+
+app = Celery("probe")
+
+@app.task
+def emit(topic: str, body: str = "") -> None: ...
+
+reveal_type(app)  # revealed: Celery[Task[(...), Any]]
+reveal_type(emit)  # revealed: Task[(...), Any]
+reveal_type(emit.delay("t"))  # revealed: AsyncResult[Any]
+
+# unchecked, and knowingly so
+emit.delay(1, 2, 3)
+
+@app.task(bind=True)
+def emit_bound(self, topic: str) -> None: ...
+
+reveal_type(emit_bound)  # revealed: Task[(...), Any]
+```

From 0f184a23c4ca6b3160e907e2325000570e94ebf9 Mon Sep 17 00:00:00 2001
From: KotlinIsland <65446343+kotlinisland@users.noreply.github.com>
Date: Sat, 8 Aug 2026 21:38:32 +1000
Subject: [PATCH 12/16] a setting is what the project's settings module says it
 is
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

the settings module a project names in `DJANGO_SETTINGS_MODULE` is resolved where
the type checker can read it, and `settings.FOO` takes the type that module gives
it, on the command line and in the editor alike

deliberately scoped, on measurement: typing django's 149 `global_settings`
defaults added sixteen diagnostics and none of them true, and the project's
container settings two more. so only non-generic values from the project's own
module are typed — zero new diagnostics over django's own corpus
---
 crates/ty/tests/cli/django.rs                 |  50 ++++
 crates/ty_ide/src/django_template.rs          |   4 +
 crates/ty_ide/src/django_template/project.rs  | 115 +--------
 crates/ty_project/src/db.rs                   |   4 +
 crates/ty_project/src/lib.rs                  |  11 +
 .../resources/mdtest/external/django.md       | 153 +++++++++++
 crates/ty_python_semantic/src/db.rs           |  14 +
 .../ty_python_semantic/src/django_settings.rs | 239 ++++++++++++++++++
 crates/ty_python_semantic/src/lib.rs          |   1 +
 crates/ty_python_semantic/src/types.rs        |  11 +
 .../ty_server/tests/e2e/django_templates.rs   |  50 ++++
 crates/ty_test/src/db.rs                      |  26 +-
 crates/ty_test/src/lib.rs                     |   2 +
 docs/basedpython/frameworks/django.md         |  22 ++
 14 files changed, 592 insertions(+), 110 deletions(-)
 create mode 100644 crates/ty_python_semantic/src/django_settings.rs

diff --git a/crates/ty/tests/cli/django.rs b/crates/ty/tests/cli/django.rs
index 8a41b9b883..971e38c5ec 100644
--- a/crates/ty/tests/cli/django.rs
+++ b/crates/ty/tests/cli/django.rs
@@ -365,3 +365,53 @@ fn a_project_without_django_reports_nothing_about_its_templates() -> anyhow::Res
 
     Ok(())
 }
+
+#[test]
+fn a_setting_has_the_type_the_settings_module_gives_it() -> anyhow::Result<()> {
+    // the settings module is found from `manage.py`, which is a fact about the
+    // project rather than about the file being checked — so this is the test that
+    // says the type checker reaches it at all, and reaches it the same way the
+    // language server does
+    let case = django_project(&[(
+        "blog/reads_settings.py",
+        "
+        from django.conf import settings
+
+        reveal_type(settings.ROOT_URLCONF)
+        reveal_type(settings.INSTALLED_APPS)
+        reveal_type(settings.NAMED_NOWHERE)
+        ",
+    )])?;
+
+    write_installed(
+        &case,
+        &[(
+            "django/conf/__init__.py",
+            "from typing import Any\n\
+             \n\
+             class LazySettings:\n\
+             \x20   def __getattr__(self, name: str) -> Any: ...\n\
+             \n\
+             settings = LazySettings()\n",
+        )],
+    )?;
+
+    // no path is named: naming one narrows the project to it, and the settings
+    // module is then no more part of the project than any other file it excludes
+    assert_cmd_snapshot!(case.command().arg("--output-format=concise"), @r"
+    success: false
+    exit_code: 1
+    ----- stdout -----
+    blog/reads_settings.py:4:1: warning[undefined-reveal] `reveal_type` used without importing it
+    blog/reads_settings.py:4:13: info[revealed-type] Revealed type: `str`
+    blog/reads_settings.py:5:1: warning[undefined-reveal] `reveal_type` used without importing it
+    blog/reads_settings.py:5:13: info[revealed-type] Revealed type: `Any`
+    blog/reads_settings.py:6:1: warning[undefined-reveal] `reveal_type` used without importing it
+    blog/reads_settings.py:6:13: info[revealed-type] Revealed type: `Any`
+    Found 6 diagnostics
+
+    ----- stderr -----
+    ");
+
+    Ok(())
+}
diff --git a/crates/ty_ide/src/django_template.rs b/crates/ty_ide/src/django_template.rs
index fea452cef9..885632a36b 100644
--- a/crates/ty_ide/src/django_template.rs
+++ b/crates/ty_ide/src/django_template.rs
@@ -269,6 +269,10 @@ impl ty_project::ProjectChecker for DjangoChecker {
     fn check_python_file(&self, db: &dyn Db, file: File) -> Vec<Diagnostic> {
         django_python_diagnostics(db, file)
     }
+
+    fn django_settings_file(&self, db: &dyn Db) -> Option<File> {
+        *project::settings_file(db, db.project())
+    }
 }
 
 /// the quick fixes offered for a template diagnostic at `range`
diff --git a/crates/ty_ide/src/django_template/project.rs b/crates/ty_ide/src/django_template/project.rs
index 68e9443669..6db4a0d899 100644
--- a/crates/ty_ide/src/django_template/project.rs
+++ b/crates/ty_ide/src/django_template/project.rs
@@ -25,11 +25,11 @@ use ruff_python_ast::{self as ast, AnyNodeRef, Expr, Stmt};
 use ruff_text_size::{Ranged, TextRange, TextSize};
 use rustc_hash::{FxHashMap, FxHashSet};
 use ty_module_resolver::{
-    Module, ModuleName, file_to_module, resolve_module, resolve_module_confident,
-    resolve_real_module,
+    Module, ModuleName, file_to_module, resolve_module_confident, resolve_real_module,
 };
 use ty_project::{Db, Project};
 use ty_python_semantic::SemanticModel;
+use ty_python_semantic::django_settings::{self as settings_source, SettingsNaming};
 use ty_python_semantic::types::ide_support::{
     ImportAliasResolution, ResolvedDefinition, definitions_for_attribute, definitions_for_name,
     instance_of_class,
@@ -45,12 +45,6 @@ const STATIC_DIRECTORY: &str = "static";
 /// the package name a project's template tag libraries live in
 const TEMPLATETAGS_PACKAGE: &str = "templatetags";
 
-/// the environment variable a project names its settings module with
-const SETTINGS_MODULE_VARIABLE: &str = "DJANGO_SETTINGS_MODULE";
-
-/// the file stem of the script whose `DJANGO_SETTINGS_MODULE` is the one that counts
-const SETTINGS_ENTRY_POINT: &str = "manage";
-
 /// the package that declares the base every test case descends from
 const UNITTEST_PACKAGE: &str = "unittest";
 
@@ -2072,15 +2066,8 @@ fn django_settings(db: &dyn Db, project: Project) -> DjangoSettings {
 /// `asgi.py`. where they disagree it is `manage.py` that decides, since that is
 /// the one a developer runs.
 #[salsa::tracked]
-fn settings_file(db: &dyn Db, project: Project) -> Option<File> {
-    let naming = settings_naming(db, project);
-
-    let naming = naming
-        .iter()
-        .find(|naming| is_entry_point(db, naming.file))
-        .or_else(|| naming.first())?;
-
-    resolve_module(db, naming.file, &ModuleName::new(&naming.module)?)?.file(db)
+pub(crate) fn settings_file(db: &dyn Db, project: Project) -> Option<File> {
+    settings_source::settings_file(db, settings_naming(db, project))
 }
 
 /// the project's `manage.py`, django's own entry point
@@ -2092,25 +2079,7 @@ fn settings_file(db: &dyn Db, project: Project) -> Option<File> {
 /// point whatever it happens to be called.
 #[salsa::tracked]
 pub(crate) fn manage_file(db: &dyn Db, project: Project) -> Option<File> {
-    settings_naming(db, project)
-        .iter()
-        .find(|naming| is_entry_point(db, naming.file))
-        .map(|naming| naming.file)
-}
-
-/// whether `file` is the script django's own `startproject` writes
-fn is_entry_point(db: &dyn Db, file: File) -> bool {
-    file.path(db)
-        .as_system_path()
-        .and_then(SystemPath::file_stem)
-        == Some(SETTINGS_ENTRY_POINT)
-}
-
-/// a file that points `DJANGO_SETTINGS_MODULE` somewhere, and where at
-#[derive(Debug, Clone, PartialEq, Eq, get_size2::GetSize)]
-struct SettingsNaming {
-    file: File,
-    module: CompactString,
+    settings_source::entry_point_file(db, settings_naming(db, project))
 }
 
 /// every file of the project that names its settings module, in path order
@@ -2119,79 +2088,7 @@ struct SettingsNaming {
 /// have to land on the same file twice running.
 #[salsa::tracked(returns(ref), heap_size=ruff_memory_usage::heap_size)]
 fn settings_naming(db: &dyn Db, project: Project) -> Box<[SettingsNaming]> {
-    let mut naming: Vec<SettingsNaming> = Vec::new();
-
-    for file in &project.files(db) {
-        // a stub sets no environment variable
-        if is_stub(db, file) {
-            continue;
-        }
-        if let Some(module) = settings_module_in_file(db, file) {
-            naming.push(SettingsNaming {
-                file,
-                module: module.clone(),
-            });
-        }
-    }
-
-    naming.sort_by(|left, right| {
-        left.file
-            .path(db)
-            .as_str()
-            .cmp(right.file.path(db).as_str())
-    });
-
-    naming.into_boxed_slice()
-}
-
-/// the settings module `file` points `DJANGO_SETTINGS_MODULE` at
-#[salsa::tracked(returns(ref), heap_size=ruff_memory_usage::heap_size)]
-fn settings_module_in_file(db: &dyn Db, file: File) -> Option<CompactString> {
-    if !mentions(db, file, &[SETTINGS_MODULE_VARIABLE]) {
-        return None;
-    }
-
-    let parsed = parsed_module(db, file).load(db);
-    let mut visitor = SettingsModuleVisitor { found: None };
-    visitor.visit_body(parsed.suite());
-
-    visitor.found
-}
-
-/// finds the one string that names the settings module
-struct SettingsModuleVisitor {
-    found: Option<CompactString>,
-}
-
-impl<'ast> Visitor<'ast> for SettingsModuleVisitor {
-    fn visit_stmt(&mut self, stmt: &'ast Stmt) {
-        // `os.environ["DJANGO_SETTINGS_MODULE"] = "project.settings"`
-        if self.found.is_none()
-            && let Stmt::Assign(assign) = stmt
-            && let [Expr::Subscript(subscript)] = assign.targets.as_slice()
-            && string_literal(&subscript.slice).as_deref() == Some(SETTINGS_MODULE_VARIABLE)
-        {
-            self.found = string_literal(&assign.value);
-            return;
-        }
-
-        walk_stmt(self, stmt);
-    }
-
-    fn visit_expr(&mut self, expr: &'ast Expr) {
-        // `os.environ.setdefault("DJANGO_SETTINGS_MODULE", "project.settings")`,
-        // and every other two-string call that sets the variable the same way
-        if self.found.is_none()
-            && let Expr::Call(call) = expr
-            && let [variable, module] = call.arguments.args.as_ref()
-            && string_literal(variable).as_deref() == Some(SETTINGS_MODULE_VARIABLE)
-        {
-            self.found = string_literal(module);
-            return;
-        }
-
-        walk_expr(self, expr);
-    }
+    settings_source::settings_namings(db, &project.files(db)).into_boxed_slice()
 }
 
 /// reads a settings module's assignments into the settings that matter here
diff --git a/crates/ty_project/src/db.rs b/crates/ty_project/src/db.rs
index 65bfcf0ec9..a521dc8b40 100644
--- a/crates/ty_project/src/db.rs
+++ b/crates/ty_project/src/db.rs
@@ -588,6 +588,10 @@ impl SemanticDb for ProjectDatabase {
         is_open_file_impl(self, file)
     }
 
+    fn django_settings_file(&self) -> Option<File> {
+        self.project_checker()?.django_settings_file(self)
+    }
+
     fn dyn_clone(&self) -> Box<dyn SemanticDb> {
         Box::new(self.clone())
     }
diff --git a/crates/ty_project/src/lib.rs b/crates/ty_project/src/lib.rs
index 764fdace77..a5d4f28101 100644
--- a/crates/ty_project/src/lib.rs
+++ b/crates/ty_project/src/lib.rs
@@ -174,6 +174,17 @@ pub trait ProjectChecker: Send + Sync + std::panic::RefUnwindSafe {
     /// [`ty_python_semantic::check_file_with`]), so that one `ty: ignore`
     /// silences either kind of diagnostic and counts as used either way.
     fn check_python_file(&self, db: &dyn Db, file: File) -> Vec<Diagnostic>;
+
+    /// The module the project points `DJANGO_SETTINGS_MODULE` at, if it names one.
+    ///
+    /// The type checker types `settings.NAME` off that module, and it is worked
+    /// out from the project's files — which is why the answer comes from here
+    /// rather than from the type checker itself. See
+    /// [`ty_python_semantic::django_settings`].
+    ///
+    /// Must be answered by a Salsa query, or an edit to the script that names the
+    /// module leaves every type inferred from it stale.
+    fn django_settings_file(&self, db: &dyn Db) -> Option<File>;
 }
 
 /// A progress reporter.
diff --git a/crates/ty_python_semantic/resources/mdtest/external/django.md b/crates/ty_python_semantic/resources/mdtest/external/django.md
index bc3baeec35..3206c75bdc 100644
--- a/crates/ty_python_semantic/resources/mdtest/external/django.md
+++ b/crates/ty_python_semantic/resources/mdtest/external/django.md
@@ -456,3 +456,156 @@ reveal_type(Book.objects.values_list("author", flat=True))  # revealed: QuerySet
 reveal_type(Author.objects.values_list("name", named=True))  # revealed: QuerySet[Author, Any]
 reveal_type(Author.objects.values_list())  # revealed: QuerySet[Author, Any]
 ```
+
+## Settings the project's settings module names
+
+`django.conf.settings` answers every attribute through `__getattr__`, so the stubs can only say
+`Any`. The project's settings module is ordinary python sitting in the project, and `manage.py` says
+which module it is, so a setting the module assigns is read off it.
+
+Only what django itself copies is read: a name is a setting when `name.isupper()`, which is the test
+django applies to the module's contents.
+
+`manage.py`:
+
+```py
+import os
+
+os.environ.setdefault("DJANGO_SETTINGS_MODULE", "conf.settings")
+```
+
+`conf/__init__.py`:
+
+```py
+```
+
+`conf/settings.py`:
+
+```py
+DEBUG = True
+ROOT_URLCONF = "conf.urls"
+SESSION_COOKIE_AGE = 1209600
+MY_CUSTOM = "anything the project likes"
+lowercase = "not a setting"
+```
+
+`app.py`:
+
+```py
+from django.conf import settings
+
+reveal_type(settings.DEBUG)  # revealed: bool
+reveal_type(settings.ROOT_URLCONF)  # revealed: str
+reveal_type(settings.SESSION_COOKIE_AGE)  # revealed: int
+reveal_type(settings.MY_CUSTOM)  # revealed: str
+
+# nothing names it, so it stays what the stubs say
+reveal_type(settings.NOT_A_SETTING_ANYWHERE)  # revealed: Any
+
+# django copies only upper-case names off the module, so this is not a setting
+reveal_type(settings.lowercase)  # revealed: Any
+
+# what the stubs declare outright still wins
+reveal_type(settings.SETTINGS_MODULE)  # revealed: str
+```
+
+## Settings whose value describes only one deployment
+
+A container's inferred element types come from the literal this deployment happens to hold, and
+django's contract is that anything may read and write keys the literal never mentions —
+`settings.DATABASES[alias]["TEST"]["USER"]` is django's own code. Such a setting keeps the `Any` the
+stubs give it rather than a type that is narrower than the setting really is.
+
+`manage.py`:
+
+```py
+import os
+
+os.environ.setdefault("DJANGO_SETTINGS_MODULE", "conf.settings")
+```
+
+`conf/__init__.py`:
+
+```py
+```
+
+`conf/settings.py`:
+
+```py
+from pathlib import Path
+
+BASE_DIR = Path(__file__).resolve().parent.parent
+DATABASES = {"default": {"ENGINE": "django.db.backends.sqlite3", "NAME": ":memory:"}}
+INSTALLED_APPS = ["django.contrib.auth"]
+```
+
+`app.py`:
+
+```py
+from django.conf import settings
+
+reveal_type(settings.DATABASES)  # revealed: Any
+reveal_type(settings.INSTALLED_APPS)  # revealed: Any
+
+# a value whose type carries no arguments has no such gap
+reveal_type(settings.BASE_DIR)  # revealed: Path
+```
+
+## No settings module named
+
+A project may configure settings programmatically with `settings.configure()`, or run with
+`DJANGO_SETTINGS_MODULE` set in its environment and written down nowhere. Nothing in the project
+says what the settings are, so every setting stays `Any`.
+
+`app.py`:
+
+```py
+from django.conf import settings
+
+settings.configure(DEBUG=True)
+
+reveal_type(settings.DEBUG)  # revealed: Any
+```
+
+## A settings module assembled from another
+
+The split-settings layout — a per-environment module that starts `from .base import *` — is read
+through the star import, since that is how the names reach the module django imports.
+
+`manage.py`:
+
+```py
+import os
+
+os.environ.setdefault("DJANGO_SETTINGS_MODULE", "conf.local")
+```
+
+`conf/__init__.py`:
+
+```py
+```
+
+`conf/base.py`:
+
+```py
+ROOT_URLCONF = "conf.urls"
+SECRET_KEY = "shared"
+```
+
+`conf/local.py`:
+
+```py
+from .base import *
+
+DEBUG = True
+```
+
+`app.py`:
+
+```py
+from django.conf import settings
+
+reveal_type(settings.DEBUG)  # revealed: bool
+reveal_type(settings.ROOT_URLCONF)  # revealed: str
+reveal_type(settings.SECRET_KEY)  # revealed: str
+```
diff --git a/crates/ty_python_semantic/src/db.rs b/crates/ty_python_semantic/src/db.rs
index 6a6716a78f..bc469c6a94 100644
--- a/crates/ty_python_semantic/src/db.rs
+++ b/crates/ty_python_semantic/src/db.rs
@@ -24,6 +24,20 @@ pub trait Db: PythonCoreDb {
     /// Expected types for string-literal completions are only collected for open files.
     fn is_open_file(&self, file: File) -> bool;
 
+    /// The module the project points `DJANGO_SETTINGS_MODULE` at, if it names one.
+    ///
+    /// Which module that is comes out of the project's own files, and enumerating
+    /// them belongs to a crate above this one, so the answer is handed down rather
+    /// than worked out here. What is left to do with it — reading `settings.NAME`
+    /// off the module — is type inference and lives here. See
+    /// [`crate::django_settings`].
+    ///
+    /// The implementation is expected to be a Salsa query, so that a change to the
+    /// script that names the module is seen by everything that read this.
+    fn django_settings_file(&self) -> Option<File> {
+        None
+    }
+
     fn dyn_clone(&self) -> Box<dyn Db>;
 }
 
diff --git a/crates/ty_python_semantic/src/django_settings.rs b/crates/ty_python_semantic/src/django_settings.rs
new file mode 100644
index 0000000000..f0852500f3
--- /dev/null
+++ b/crates/ty_python_semantic/src/django_settings.rs
@@ -0,0 +1,239 @@
+//! the settings module a django project points `DJANGO_SETTINGS_MODULE` at
+//!
+//! finding it needs the project's files, which is a notion of a crate above this
+//! one. what lives here is the reading of a single file and the rule that picks
+//! between the files that name a module — everything except the enumeration —
+//! so that the type checker, the language server's django front end and the
+//! mdtest harness all land on the same module by the same rule.
+//!
+//! nothing here guesses. a module is only the settings module because a script
+//! of the project assigns `DJANGO_SETTINGS_MODULE` to its name; a project that
+//! configures settings some other way names nothing and gets nothing.
+
+use compact_str::{CompactString, ToCompactString};
+use ruff_db::files::File;
+use ruff_db::parsed::parsed_module;
+use ruff_db::source::source_text;
+use ruff_db::system::SystemPath;
+use ruff_python_ast::name::Name;
+use ruff_python_ast::visitor::{Visitor, walk_expr, walk_stmt};
+use ruff_python_ast::{Expr, Stmt};
+use ty_module_resolver::{ModuleName, file_to_module, resolve_module};
+
+use crate::Db;
+use crate::place::imported_symbol;
+use crate::types::{ClassType, Type};
+
+/// the environment variable a project names its settings module with
+const SETTINGS_MODULE_VARIABLE: &str = "DJANGO_SETTINGS_MODULE";
+
+/// the file stem of the script whose `DJANGO_SETTINGS_MODULE` is the one that counts
+const SETTINGS_ENTRY_POINT: &str = "manage";
+
+/// the module `django.conf.settings` is an instance of a class from
+const SETTINGS_MODULE: &str = "django.conf";
+
+/// the class `django.conf.settings` is an instance of
+const SETTINGS_CLASS: &str = "LazySettings";
+
+/// a file that points `DJANGO_SETTINGS_MODULE` somewhere, and where at
+#[derive(Debug, Clone, PartialEq, Eq, get_size2::GetSize)]
+pub struct SettingsNaming {
+    pub file: File,
+    pub module: CompactString,
+}
+
+/// every file of `files` that names a settings module, in path order
+///
+/// the caller's files come in no order worth relying on, and every consumer has
+/// to land on the same file twice running.
+pub fn settings_namings(db: &dyn Db, files: impl IntoIterator<Item = File>) -> Vec<SettingsNaming> {
+    let mut namings: Vec<SettingsNaming> = files
+        .into_iter()
+        // a stub sets no environment variable
+        .filter(|file| !is_stub(db, *file))
+        .filter_map(|file| {
+            Some(SettingsNaming {
+                file,
+                module: settings_module_in_file(db, file).clone()?,
+            })
+        })
+        .collect();
+
+    namings.sort_by(|left, right| {
+        left.file
+            .path(db)
+            .as_str()
+            .cmp(right.file.path(db).as_str())
+    });
+
+    namings
+}
+
+/// the settings module the namings point `DJANGO_SETTINGS_MODULE` at
+///
+/// a project names it in `manage.py`, and usually again in its `wsgi.py` and
+/// `asgi.py`. where they disagree it is `manage.py` that decides, since that is
+/// the one a developer runs.
+pub fn settings_file(db: &dyn Db, namings: &[SettingsNaming]) -> Option<File> {
+    let naming = namings
+        .iter()
+        .find(|naming| is_entry_point(db, naming.file))
+        .or_else(|| namings.first())?;
+
+    resolve_module(db, naming.file, &ModuleName::new(&naming.module)?)?.file(db)
+}
+
+/// the naming that is django's own entry point, the script `manage.py test`,
+/// `manage.py migrate` and the rest are run through
+pub fn entry_point_file(db: &dyn Db, namings: &[SettingsNaming]) -> Option<File> {
+    namings
+        .iter()
+        .find(|naming| is_entry_point(db, naming.file))
+        .map(|naming| naming.file)
+}
+
+/// whether `file` is the script django's own `startproject` writes
+fn is_entry_point(db: &dyn Db, file: File) -> bool {
+    file.path(db)
+        .as_system_path()
+        .and_then(SystemPath::file_stem)
+        == Some(SETTINGS_ENTRY_POINT)
+}
+
+fn is_stub(db: &dyn Db, file: File) -> bool {
+    matches!(file.path(db).extension(), Some("pyi" | "byi"))
+}
+
+/// the settings module `file` points `DJANGO_SETTINGS_MODULE` at
+#[salsa::tracked(returns(ref), heap_size=ruff_memory_usage::heap_size)]
+pub fn settings_module_in_file(db: &dyn Db, file: File) -> Option<CompactString> {
+    if !source_text(db, file).contains(SETTINGS_MODULE_VARIABLE) {
+        return None;
+    }
+
+    let parsed = parsed_module(db, file).load(db);
+    let mut visitor = SettingsModuleVisitor { found: None };
+    visitor.visit_body(parsed.suite());
+
+    visitor.found
+}
+
+/// finds the one string that names the settings module
+struct SettingsModuleVisitor {
+    found: Option<CompactString>,
+}
+
+impl<'ast> Visitor<'ast> for SettingsModuleVisitor {
+    fn visit_stmt(&mut self, stmt: &'ast Stmt) {
+        // `os.environ["DJANGO_SETTINGS_MODULE"] = "project.settings"`
+        if self.found.is_none()
+            && let Stmt::Assign(assign) = stmt
+            && let [Expr::Subscript(subscript)] = assign.targets.as_slice()
+            && string_literal(&subscript.slice).as_deref() == Some(SETTINGS_MODULE_VARIABLE)
+        {
+            self.found = string_literal(&assign.value);
+            return;
+        }
+
+        walk_stmt(self, stmt);
+    }
+
+    fn visit_expr(&mut self, expr: &'ast Expr) {
+        // `os.environ.setdefault("DJANGO_SETTINGS_MODULE", "project.settings")`,
+        // and every other two-string call that sets the variable the same way
+        if self.found.is_none()
+            && let Expr::Call(call) = expr
+            && let [variable, module] = call.arguments.args.as_ref()
+            && string_literal(variable).as_deref() == Some(SETTINGS_MODULE_VARIABLE)
+        {
+            self.found = string_literal(module);
+            return;
+        }
+
+        walk_expr(self, expr);
+    }
+}
+
+/// whether `ty` is `django.conf.settings` — the one object whose attributes are
+/// the project's settings
+pub(crate) fn is_settings_instance(db: &dyn Db, ty: Type<'_>) -> bool {
+    // a `LazySettings()` built by hand is inferred exactly, and the restriction
+    // says nothing about which class it is
+    let Type::NominalInstance(instance) = ty.erase_restriction(db) else {
+        return false;
+    };
+    let class = instance.class(db).class_literal(db);
+
+    class.name(db) == SETTINGS_CLASS
+        && file_to_module(db, class.file(db))
+            .is_some_and(|module| module.name(db) == SETTINGS_MODULE)
+}
+
+/// the type `django.conf.settings.NAME` has, read off the module the project
+/// points `DJANGO_SETTINGS_MODULE` at
+///
+/// `None` — which leaves the stubs' `__getattr__` to answer `Any`, as it does
+/// today — whenever the module cannot be reached, does not bind the name, or
+/// binds it to something whose type says less than it appears to. see
+/// [`describes_the_setting`].
+pub(crate) fn settings_member<'db>(db: &'db dyn Db, name: &Name) -> Option<Type<'db>> {
+    // django copies a name off the settings module only when `name.isupper()`,
+    // so a module's `BASE_DIR` is a setting and its `os` is not
+    if !is_setting_name(name) {
+        return None;
+    }
+
+    let module = db.django_settings_file()?;
+    let member = imported_symbol(db, Some(module), name, None)
+        .place
+        .ignore_possibly_undefined()?
+        // the module assigns one deployment's value; what the setting *is* is the
+        // type of that value, not the value
+        .promote(db);
+
+    describes_the_setting(db, member).then_some(member)
+}
+
+/// python's `str.isupper`, which is the test django copies a name by
+fn is_setting_name(name: &Name) -> bool {
+    let mut cased = false;
+    for character in name.chars() {
+        if character.is_lowercase() {
+            return false;
+        }
+        cased |= character.is_uppercase();
+    }
+    cased
+}
+
+/// whether a settings module's binding says what the setting is, rather than
+/// only what this deployment happens to put in it
+///
+/// a container literal is the second kind. `DATABASES = {"default": {"ENGINE":
+/// ..., "NAME": ...}}` infers `dict[str, dict[str, str]]`, but django's contract
+/// is that anything may read and write keys the literal never mentions —
+/// `settings.DATABASES[alias]["TEST"]["USER"]` is django's own code — so the
+/// inferred element types are narrower than the setting. a value whose type
+/// carries no arguments has no such gap: `ROOT_URLCONF = "project.urls"` is a
+/// `str` and there is nothing about the string's contents to be too narrow
+/// about.
+fn describes_the_setting(db: &dyn Db, ty: Type<'_>) -> bool {
+    match ty {
+        Type::NominalInstance(instance) => {
+            matches!(instance.class(db), ClassType::NonGeneric(_))
+        }
+        Type::Union(union) => union
+            .elements(db)
+            .iter()
+            .all(|element| describes_the_setting(db, *element)),
+        _ => false,
+    }
+}
+
+fn string_literal(expr: &Expr) -> Option<CompactString> {
+    match expr {
+        Expr::StringLiteral(literal) => Some(literal.value.to_str().to_compact_string()),
+        _ => None,
+    }
+}
diff --git a/crates/ty_python_semantic/src/lib.rs b/crates/ty_python_semantic/src/lib.rs
index bef4745b8e..4fb675aa6f 100644
--- a/crates/ty_python_semantic/src/lib.rs
+++ b/crates/ty_python_semantic/src/lib.rs
@@ -57,6 +57,7 @@ pub use types::{DisplaySettings, TypeQualifiers};
 
 pub mod api_lockfile;
 mod db;
+pub mod django_settings;
 pub mod django_template;
 mod dunder_all;
 mod fixes;
diff --git a/crates/ty_python_semantic/src/types.rs b/crates/ty_python_semantic/src/types.rs
index 387df02194..f30573370f 100644
--- a/crates/ty_python_semantic/src/types.rs
+++ b/crates/ty_python_semantic/src/types.rs
@@ -57,6 +57,7 @@ pub(crate) use self::signatures::Signature;
 pub(crate) use self::subclass_of::{SubclassOfInner, SubclassOfType};
 pub(crate) use self::type_expansion::expand_type;
 pub use crate::diagnostic::add_inferred_python_version_hint_to_diagnostic;
+use crate::django_settings;
 use crate::place::{
     DefinedPlace, Definedness, Place, PlaceAndQualifiers, Provenance, TypeOrigin,
     builtins_module_scope, imported_symbol, known_module_symbol, place_from_bindings,
@@ -6207,6 +6208,16 @@ impl<'db> Type<'db> {
                 return Place::Undefined.into();
             }
 
+            // `django.conf.settings` answers every name through `__getattr__`, but a
+            // project that names its settings module says there what each of them
+            // is. that reading comes first, and anything it cannot answer falls
+            // through to the `Any` the stubs declare
+            if django_settings::is_settings_instance(db, self)
+                && let Some(setting) = django_settings::settings_member(db, name)
+            {
+                return Place::bound(setting).into();
+            }
+
             self.try_call_dunder(
                 db,
                 "__getattr__",
diff --git a/crates/ty_server/tests/e2e/django_templates.rs b/crates/ty_server/tests/e2e/django_templates.rs
index 40cf986689..e7bab94fca 100644
--- a/crates/ty_server/tests/e2e/django_templates.rs
+++ b/crates/ty_server/tests/e2e/django_templates.rs
@@ -1179,3 +1179,53 @@ fn a_management_command_that_wants_a_terminal_is_refused_rather_than_spawned() -
 
     Ok(())
 }
+
+#[test]
+fn a_setting_hovers_as_the_type_the_settings_module_gives_it() -> Result<()> {
+    // the type checker reaches the settings module through the same registered
+    // project checker the command line registers, and this is what says the server
+    // registers it too: the same file checked either way says `str` either way
+    const READER: &str = "\
+from django.conf import settings
+
+value = settings.ROOT_URLCONF
+";
+
+    let mut server = TestServerBuilder::new()?
+        .with_workspace(SystemPath::new("src"), None)?
+        .with_file(
+            SystemPath::new("src/manage.py"),
+            "import os\n\nos.environ.setdefault('DJANGO_SETTINGS_MODULE', 'project.settings')\n",
+        )?
+        .with_file(SystemPath::new("src/project/__init__.py"), "")?
+        .with_file(
+            SystemPath::new("src/project/settings.py"),
+            "ROOT_URLCONF = 'project.urls'\n",
+        )?
+        .with_file(
+            SystemPath::new("src/django/conf/__init__.py"),
+            "from typing import Any\n\
+             \n\
+             class LazySettings:\n\
+             \x20   def __getattr__(self, name: str) -> Any: ...\n\
+             \n\
+             settings = LazySettings()\n",
+        )?
+        .with_file(SystemPath::new("src/blog/reads_settings.py"), READER)?
+        .build()
+        .wait_until_workspaces_are_initialized();
+
+    server.open_text_document(SystemPath::new("src/blog/reads_settings.py"), READER, 1);
+
+    let hover = server
+        .hover_request(
+            SystemPath::new("src/blog/reads_settings.py"),
+            Position::new(2, 20),
+        )
+        .expect("a hover response");
+
+    let rendered = format!("{:?}", hover.contents);
+    assert!(rendered.contains(r#"value: "str""#), "got {rendered}");
+
+    Ok(())
+}
diff --git a/crates/ty_test/src/db.rs b/crates/ty_test/src/db.rs
index 2f150c55b0..7b309d1096 100644
--- a/crates/ty_test/src/db.rs
+++ b/crates/ty_test/src/db.rs
@@ -19,7 +19,7 @@ use ty_python_core::Db as _;
 use ty_python_core::program::Program;
 use ty_python_semantic::lint::{LintRegistry, RuleSelection};
 use ty_python_semantic::{
-    AnalysisSettings, Db as SemanticDb, check_file_unwrap, default_lint_registry,
+    AnalysisSettings, Db as SemanticDb, check_file_unwrap, default_lint_registry, django_settings,
 };
 
 #[salsa::db]
@@ -54,6 +54,19 @@ impl Db {
         self.settings.unwrap()
     }
 
+    /// Records the files the test defines, which is what the settings module a
+    /// django test names is looked for among.
+    ///
+    /// A Salsa input, because the tests of one markdown file share a database:
+    /// a type inferred from the settings module of one test must not be handed
+    /// to the next, whose files are different.
+    pub(crate) fn set_project_files(&mut self, files: Vec<File>) {
+        let settings = self.settings();
+        if settings.project_files(self) != &files {
+            settings.set_project_files(self).to(files);
+        }
+    }
+
     pub(crate) fn set_verbosity(&mut self, verbose: bool) {
         self.settings().set_verbose(self).to(verbose);
     }
@@ -156,6 +169,14 @@ impl SemanticDb for Db {
         false
     }
 
+    fn django_settings_file(&self) -> Option<File> {
+        let namings = django_settings::settings_namings(
+            self,
+            self.settings().project_files(self).iter().copied(),
+        );
+        django_settings::settings_file(self, &namings)
+    }
+
     fn analysis_settings(&self, file: File) -> &AnalysisSettings {
         file_settings(self, file).analysis(self)
     }
@@ -227,6 +248,9 @@ struct Settings {
     #[default]
     #[returns(copy)]
     verbose: bool,
+    #[default]
+    #[returns(ref)]
+    project_files: Vec<File>,
 }
 
 #[derive(Clone, Debug, PartialEq, Eq)]
diff --git a/crates/ty_test/src/lib.rs b/crates/ty_test/src/lib.rs
index 2735ec780e..75d91594f7 100644
--- a/crates/ty_test/src/lib.rs
+++ b/crates/ty_test/src/lib.rs
@@ -235,6 +235,8 @@ fn run_test(
         })
         .collect();
 
+    db.set_project_files(test_files.iter().map(|test_file| test_file.file).collect());
+
     // Create a custom typeshed `VERSIONS` file if none was provided.
     if let Some(typeshed_path) = custom_typeshed_path {
         db.files()
diff --git a/docs/basedpython/frameworks/django.md b/docs/basedpython/frameworks/django.md
index 2446469e55..9c7630c622 100644
--- a/docs/basedpython/frameworks/django.md
+++ b/docs/basedpython/frameworks/django.md
@@ -59,6 +59,28 @@ a view or serializer that *does* write its type argument keeps it — the substi
 
 `.data` and `.validated_data` stay `Any` on purpose — see below
 
+### settings
+
+`django.conf.settings` answers every name through `__getattr__`, so the stubs can only say `Any`. your settings module is ordinary python sitting in your project, and `manage.py` says which module it is, so a setting the module assigns is read off it:
+
+```by
+from django.conf import settings
+
+settings.ROOT_URLCONF   # str
+settings.DEBUG          # bool
+settings.MY_OWN         # whatever your settings module assigns it
+```
+
+the module comes from the `DJANGO_SETTINGS_MODULE` your own scripts assign — `manage.py` first, then `wsgi.py` or `asgi.py`. nothing is guessed: a project that configures settings with `settings.configure()`, or names the module only in its environment, gets today's `Any` for every setting
+
+a split-settings layout is read through its star import, so `from .base import *` in the module `manage.py` names brings `base`'s settings along
+
+these stay `Any` on purpose:
+
+- a setting whose value is a container. `DATABASES = {"default": {...}}` infers `dict[str, dict[str, str]]` from what one deployment happens to hold, and django's contract is that anything may read and write keys the literal never mentions — `settings.DATABASES[alias]["TEST"]["USER"]` is django's own code
+- a setting your module does not assign, even one `django.conf.global_settings` gives a default for. django's own code is written to survive a settings module putting anything in them, and typing them turns that defensive code into errors
+- writing a setting. `settings.DEBUG = 1` is what `override_settings` does, and it is checked no more strictly than before
+
 ### transpilation compatibility
 
 - `optional?.chaining` works across nullable relations: `author?.birthday?.year`

From c6ee9e5a46049c22247a69f4509f48b6ff49d172 Mon Sep 17 00:00:00 2001
From: KotlinIsland <65446343+kotlinisland@users.noreply.github.com>
Date: Sat, 8 Aug 2026 21:38:32 +1000
Subject: [PATCH 13/16] a template suppression that silenced nothing says so
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

matching ty's own python semantics rather than inventing any, including reporting
a suppression whose rule is turned off in configuration — measured, that is what
python does

with one template-only gate: a check that bailed because its index could not
answer has decided nothing, so its suppression is never called unused
---
 Cargo.lock                                    |   1 +
 crates/ty_ide/Cargo.toml                      |   1 +
 crates/ty_ide/src/django_template.rs          |  35 +-
 .../ty_ide/src/django_template/diagnostics.rs | 656 +++++++++++++++++-
 .../frameworks/django-templates.md            |   2 +
 5 files changed, 663 insertions(+), 32 deletions(-)

diff --git a/Cargo.lock b/Cargo.lock
index ba2e34f4da..d5c02b1493 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -4781,6 +4781,7 @@ dependencies = [
  "ruff_python_parser",
  "ruff_python_stdlib",
  "ruff_python_trivia",
+ "ruff_ranged_value",
  "ruff_source_file",
  "ruff_text_size",
  "rustc-hash",
diff --git a/crates/ty_ide/Cargo.toml b/crates/ty_ide/Cargo.toml
index 17d16d76a4..f44d4e2ae4 100644
--- a/crates/ty_ide/Cargo.toml
+++ b/crates/ty_ide/Cargo.toml
@@ -49,6 +49,7 @@ tracing = { workspace = true }
 
 [dev-dependencies]
 ruff_python_parser = { workspace = true }
+ruff_ranged_value = { workspace = true }
 ty_project = { workspace = true, features = ["testing"] }
 
 camino = { workspace = true }
diff --git a/crates/ty_ide/src/django_template.rs b/crates/ty_ide/src/django_template.rs
index 885632a36b..5b84477e98 100644
--- a/crates/ty_ide/src/django_template.rs
+++ b/crates/ty_ide/src/django_template.rs
@@ -406,13 +406,16 @@ pub(crate) mod tests {
     use ruff_db::system::{DbWithTestSystem, DbWithWritableSystem, SystemPath, SystemPathBuf};
     use ruff_python_ast::PythonVersion;
     use ruff_python_trivia::textwrap::dedent;
+    use ruff_ranged_value::RangedValue;
     use ruff_text_size::{Ranged, TextLen, TextRange, TextSize};
     use std::ops::Range;
     use ty_module_resolver::SearchPathSettings;
+    use ty_project::metadata::options::{Options, Rules};
     use ty_project::{ProjectMetadata, TestDb};
     use ty_python_core::platform::PythonPlatform;
     use ty_python_core::program::{FallibleStrategy, Program, ProgramSettings};
     use ty_python_semantic::PythonVersionWithSource;
+    use ty_python_semantic::lint::Level;
 
     use crate::MarkupKind;
 
@@ -550,11 +553,41 @@ pub(crate) mod tests {
         pub(crate) fn with_site_packages(
             sources: &[(&str, &str)],
             installed: &[(&str, &str)],
+        ) -> Self {
+            Self::with_rules(sources, installed, &[])
+        }
+
+        /// the same again, with some rules set to a level of their own
+        ///
+        /// the rule selection is part of the project's metadata, so a test that
+        /// needs a rule turned off has to say so before the project is built.
+        pub(crate) fn with_rules(
+            sources: &[(&str, &str)],
+            installed: &[(&str, &str)],
+            rules: &[(&str, Level)],
         ) -> Self {
             let root = SystemPathBuf::from("/src");
             let site_packages = SystemPathBuf::from("/site-packages");
 
-            let mut db = TestDb::new(ProjectMetadata::new("test", root.clone()));
+            let mut metadata = ProjectMetadata::new("test", root.clone());
+            if !rules.is_empty() {
+                metadata.apply_override_options(Options {
+                    rules: Some(
+                        rules
+                            .iter()
+                            .map(|(rule, level)| {
+                                (
+                                    RangedValue::cli((*rule).to_string()),
+                                    RangedValue::cli(*level),
+                                )
+                            })
+                            .collect::<Rules>(),
+                    ),
+                    ..Options::default()
+                });
+            }
+
+            let mut db = TestDb::new(metadata);
 
             for (path, contents) in installed {
                 db.write_file(site_packages.join(path), dedent(contents).as_ref())
diff --git a/crates/ty_ide/src/django_template/diagnostics.rs b/crates/ty_ide/src/django_template/diagnostics.rs
index a1bfa21882..7f55ccf4ab 100644
--- a/crates/ty_ide/src/django_template/diagnostics.rs
+++ b/crates/ty_ide/src/django_template/diagnostics.rs
@@ -21,6 +21,7 @@ use ruff_source_file::OneIndexed;
 use ruff_text_size::{TextRange, TextSize};
 use rustc_hash::FxHashSet;
 use ty_project::Db;
+use ty_python_semantic::UNUSED_IGNORE_COMMENT;
 use ty_python_semantic::django_template::{
     INVALID_ROUTE_ARGUMENTS, TEMPLATE_MEMBER_ALTERS_DATA, TEMPLATE_MEMBER_NEEDS_ARGUMENTS,
     UNCLOSED_TEMPLATE_BLOCK, UNKNOWN_TEMPLATE_BLOCK, UNKNOWN_TEMPLATE_FILTER,
@@ -64,10 +65,39 @@ pub(crate) struct Checker<'a> {
     /// tags and filters cannot be enumerated, whatever the project-wide index
     /// says, so this is per template rather than per project.
     libraries_known: bool,
+    /// whether the settings index answers for the whole project
+    ///
+    /// every check reads something the settings decide, so nothing at all is
+    /// decided about this file without them
+    settings_known: bool,
     suppressions: Suppressions,
+    /// the rules whose check reached a conclusion for this file
+    ///
+    /// see [`Checker::decides`]
+    decided: Vec<LintId>,
     found: Vec<Diagnostic>,
 }
 
+/// every rule a template can report
+///
+/// a blanket `{# ty: ignore #}` covers all of them at once, so it is only ever
+/// unused when every one of them was decided.
+const TEMPLATE_LINTS: &[&LintMetadata] = &[
+    &UNCLOSED_TEMPLATE_BLOCK,
+    &UNMATCHED_TEMPLATE_CLOSE,
+    &UNKNOWN_TEMPLATE_LIBRARY,
+    &UNKNOWN_TEMPLATE_TAG,
+    &UNKNOWN_TEMPLATE_FILTER,
+    &UNLOADED_TEMPLATE_LIBRARY,
+    &UNRESOLVED_TEMPLATE,
+    &UNRESOLVED_STATIC_FILE,
+    &UNRESOLVED_ROUTE,
+    &INVALID_ROUTE_ARGUMENTS,
+    &UNKNOWN_TEMPLATE_BLOCK,
+    &TEMPLATE_MEMBER_NEEDS_ARGUMENTS,
+    &TEMPLATE_MEMBER_ALTERS_DATA,
+];
+
 /// everything wrong with `file`, read as a django template
 pub(crate) fn diagnostics(
     db: &dyn Db,
@@ -78,7 +108,8 @@ pub(crate) fn diagnostics(
     let project = db.project();
     let loaded = loaded_libraries(db, index);
 
-    let libraries_known = project::settings_are_authoritative(db, project)
+    let settings_known = project::settings_are_authoritative(db, project);
+    let libraries_known = settings_known
         && index.loads().iter().all(|load| {
             project::tag_libraries(db, project)
                 .iter()
@@ -92,7 +123,9 @@ pub(crate) fn diagnostics(
         source,
         loaded,
         libraries_known,
+        settings_known,
         suppressions: Suppressions::of(index, source),
+        decided: Vec::new(),
         found: Vec::new(),
     };
 
@@ -105,6 +138,8 @@ pub(crate) fn diagnostics(
     checker.routes();
     checker.unknown_blocks();
     checker.members_needing_arguments();
+    // last, since it answers for what every check above did or did not silence
+    checker.unused_suppressions();
 
     checker.found.sort_by_key(|diagnostic| {
         diagnostic
@@ -132,10 +167,8 @@ impl Checker<'_> {
             .rule_selection(self.file)
             .severity(LintId::of(lint))?;
 
-        if self
-            .suppressions
-            .covers(lint, line_of(self.source, range.start()))
-        {
+        let line = line_of(self.source, range.start());
+        if self.suppressions.silences(lint, line) {
             return None;
         }
 
@@ -146,6 +179,20 @@ impl Checker<'_> {
         self.found.last_mut()
     }
 
+    /// record that the check for each of `lints` reached a conclusion
+    ///
+    /// this is what an unused suppression is answered from. a check that bailed —
+    /// because the settings, the tag libraries or the url tree could not be read —
+    /// has decided nothing about the file, and a comment silencing its rule is
+    /// doing a job the moment those can be read, so it is not one to call unused.
+    fn decides(&mut self, lints: &[&'static LintMetadata]) {
+        if !self.settings_known {
+            return;
+        }
+
+        self.decided.extend(lints.iter().copied().map(LintId::of));
+    }
+
     fn text(&self, range: TextRange) -> &str {
         &self.source[range]
     }
@@ -158,6 +205,8 @@ impl Checker<'_> {
     /// open one because the file happens to hold a matching `{% end… %}`
     /// elsewhere is a guess, and a guess is not something to report.
     fn unclosed_blocks(&mut self) {
+        self.decides(&[&UNCLOSED_TEMPLATE_BLOCK]);
+
         let unclosed: Vec<_> = self
             .index
             .spans()
@@ -185,6 +234,8 @@ impl Checker<'_> {
     /// `{% endmodal %}` belonging to a project's own block tag is left alone,
     /// since nothing here knows whether `{% modal %}` opens a block at all.
     fn unmatched_closes(&mut self) {
+        self.decides(&[&UNMATCHED_TEMPLATE_CLOSE]);
+
         let strays: Vec<_> = self
             .index
             .strays()
@@ -214,6 +265,7 @@ impl Checker<'_> {
         if !project::settings_are_authoritative(self.db, self.db.project()) {
             return;
         }
+        self.decides(&[&UNKNOWN_TEMPLATE_LIBRARY]);
 
         let unknown: Vec<_> = self
             .index
@@ -242,6 +294,11 @@ impl Checker<'_> {
         if !self.libraries_known {
             return;
         }
+        self.decides(&[
+            &UNKNOWN_TEMPLATE_TAG,
+            &UNKNOWN_TEMPLATE_FILTER,
+            &UNLOADED_TEMPLATE_LIBRARY,
+        ]);
 
         let mut checked: Vec<(bool, CompactString, TextRange)> = Vec::new();
 
@@ -372,6 +429,7 @@ impl Checker<'_> {
         if !project::settings_are_authoritative(self.db, self.db.project()) {
             return;
         }
+        self.decides(&[&UNRESOLVED_TEMPLATE]);
 
         let missing: Vec<_> = self
             .index
@@ -399,6 +457,7 @@ impl Checker<'_> {
         if !project::settings_are_authoritative(self.db, self.db.project()) {
             return;
         }
+        self.decides(&[&UNRESOLVED_STATIC_FILE]);
 
         let files = project::static_files(self.db, self.db.project());
         let named: Vec<_> = self
@@ -438,6 +497,7 @@ impl Checker<'_> {
         if !project::routes_are_authoritative(self.db, self.db.project()) {
             return;
         }
+        self.decides(&[&UNRESOLVED_ROUTE, &INVALID_ROUTE_ARGUMENTS]);
 
         let mut unresolved = Vec::new();
         let mut invalid = Vec::new();
@@ -593,6 +653,9 @@ impl Checker<'_> {
 
     fn unknown_blocks(&mut self) {
         if self.index.extends().is_none() {
+            // a template that overrides nothing has no block that could be
+            // unknown, which is a conclusion rather than a bail-out
+            self.decides(&[&UNKNOWN_TEMPLATE_BLOCK]);
             return;
         }
 
@@ -605,6 +668,7 @@ impl Checker<'_> {
         if !complete {
             return;
         }
+        self.decides(&[&UNKNOWN_TEMPLATE_BLOCK]);
 
         let declared: FxHashSet<CompactString> = chain
             .iter()
@@ -654,6 +718,11 @@ impl Checker<'_> {
     /// `alters_data` before it attempts the call, so a write method that also
     /// needs arguments is refused rather than uncallable.
     fn members_needing_arguments(&mut self) {
+        self.decides(&[
+            &TEMPLATE_MEMBER_NEEDS_ARGUMENTS,
+            &TEMPLATE_MEMBER_ALTERS_DATA,
+        ]);
+
         let mut found = Vec::new();
         let mut refused = Vec::new();
 
@@ -715,6 +784,146 @@ impl Checker<'_> {
         }
     }
 
+    // ---- 13. a suppression comment that silenced nothing --------------------
+
+    /// a `{# ty: ignore #}` that turned out to be doing nothing
+    ///
+    /// this is `unused-ignore-comment` as a python file reports it — a comment
+    /// that silenced nothing is a comment whose removal changes nothing, and
+    /// leaving it there hides the day the rule starts firing again. the semantics
+    /// are the python ones down to a rule that configuration has turned off: the
+    /// check never runs, so the comment never silences anything, so it is unused.
+    ///
+    /// what a template adds is that a check can decline to answer at all — see
+    /// [`Checker::decides`] — and a rule that was never decided is left alone.
+    fn unused_suppressions(&mut self) {
+        let Some(severity) = self
+            .db
+            .rule_selection(self.file)
+            .severity(LintId::of(&UNUSED_IGNORE_COMMENT))
+        else {
+            return;
+        };
+
+        // the checks are all done with it, and reporting needs to mark codes used
+        // as it goes
+        let mut suppressions = std::mem::take(&mut self.suppressions);
+
+        let blanket_answerable = TEMPLATE_LINTS
+            .iter()
+            .all(|lint| self.decided.contains(&LintId::of(lint)));
+
+        // one candidate per code rather than per comment, so that a code can
+        // silence a sibling's report the way it does in a python file
+        let mut candidates = Vec::new();
+        for (entry, suppression) in suppressions.entries.iter().enumerate() {
+            if suppression.rules.is_empty() {
+                if !suppression.used && blanket_answerable {
+                    candidates.push(Reported { entry, code: None });
+                }
+                continue;
+            }
+
+            candidates.extend(
+                suppression
+                    .rules
+                    .iter()
+                    .enumerate()
+                    .filter(|(_, rule)| !rule.used && self.answers_for(&rule.name))
+                    .map(|(code, _)| Reported {
+                        entry,
+                        code: Some(code),
+                    }),
+            );
+        }
+
+        // a comment naming `unused-ignore-comment` silences these, and the code
+        // being reported cannot silence itself
+        let mut reported = Vec::new();
+        for candidate in candidates {
+            let line = suppressions.entries[candidate.entry].line;
+            match suppressions.unused_silencer(line, candidate) {
+                Some(silencer) => suppressions.mark_used(silencer),
+                None => reported.push(candidate),
+            }
+        }
+
+        // a code that went on to silence one of these is no longer unused
+        reported.retain(|candidate| !suppressions.is_used(*candidate));
+
+        // a comment every one of whose codes went unused is reported whole, since
+        // the whole comment is then what there is to take out
+        let whole_comments: Vec<usize> = suppressions
+            .entries
+            .iter()
+            .enumerate()
+            .filter(|(entry, suppression)| {
+                !suppression.rules.is_empty()
+                    && reported
+                        .iter()
+                        .filter(|candidate| candidate.entry == *entry)
+                        .count()
+                        == suppression.rules.len()
+            })
+            .map(|(entry, _)| entry)
+            .collect();
+        reported.retain(|candidate| {
+            !whole_comments.contains(&candidate.entry) || candidate.code == Some(0)
+        });
+
+        for candidate in &reported {
+            let suppression = &suppressions.entries[candidate.entry];
+            let whole = whole_comments.contains(&candidate.entry);
+
+            let (range, message) = match candidate.code.filter(|_| !whole) {
+                Some(code) => (
+                    suppression.rules[code].range,
+                    format!(
+                        "unused `ty: ignore` directive: `{}`",
+                        suppression.rules[code].name
+                    ),
+                ),
+                None if suppression.rules.is_empty() => (
+                    suppression.range,
+                    "unused blanket `ty: ignore` directive".to_string(),
+                ),
+                None => (
+                    suppression.range,
+                    "unused `ty: ignore` directive".to_string(),
+                ),
+            };
+
+            let mut diagnostic = Diagnostic::new(
+                DiagnosticId::Lint(UNUSED_IGNORE_COMMENT.name()),
+                severity,
+                message,
+            );
+            diagnostic.annotate(Annotation::primary(Span::from(self.file).with_range(range)));
+            diagnostic.help("remove the unused suppression");
+            diagnostic.set_fix(match candidate.code.filter(|_| !whole) {
+                Some(code) => remove_code_fix(self.source, suppression, code),
+                None => remove_comment_fix(self.source, suppression),
+            });
+            self.found.push(diagnostic);
+        }
+    }
+
+    /// whether an unused suppression naming `rule` is one to report
+    ///
+    /// a code naming a rule no template check produces — a python one, or a
+    /// misspelling — is left alone: nothing here has looked for it, so nothing
+    /// here can say it went unused.
+    fn answers_for(&self, rule: &str) -> bool {
+        if rule == &*UNUSED_IGNORE_COMMENT.name() {
+            return true;
+        }
+
+        TEMPLATE_LINTS
+            .iter()
+            .filter(|lint| rule == &*lint.name())
+            .any(|lint| self.decided.contains(&LintId::of(lint)))
+    }
+
     // ---- reading a construct's arguments -----------------------------------
 
     /// the first argument of every `{% tag %}` of this name that writes a string
@@ -979,8 +1188,25 @@ struct Suppression {
     line: OneIndexed,
     /// whether the comment stands alone, and so covers the line below it too
     alone: bool,
+    /// the whole comment, `{#` and `#}` included
+    range: TextRange,
     /// the rules it names, or nothing for a blanket one
-    rules: Vec<CompactString>,
+    rules: Vec<Rule>,
+    /// whether a blanket comment silenced anything
+    ///
+    /// a comment naming rules answers for each of them separately, so this stays
+    /// false there.
+    used: bool,
+}
+
+/// one rule code written inside a suppression comment
+#[derive(Debug)]
+struct Rule {
+    name: CompactString,
+    /// the range of the code itself, brackets and commas excluded
+    range: TextRange,
+    /// whether this code silenced a diagnostic
+    used: bool,
 }
 
 /// what a suppression comment is written with
@@ -995,7 +1221,8 @@ impl Suppressions {
                 continue;
             }
 
-            let body = source[construct.range]
+            let comment = &source[construct.range];
+            let body = comment
                 .trim_start_matches("{#")
                 .trim_end_matches("#}")
                 .trim();
@@ -1005,17 +1232,17 @@ impl Suppressions {
             let rules = match rules.trim() {
                 "" => Vec::new(),
                 rules => {
-                    let Some(named) = rules
-                        .strip_prefix('[')
-                        .and_then(|rules| rules.strip_suffix(']'))
-                    else {
+                    if !rules.starts_with('[') || !rules.ends_with(']') {
+                        continue;
+                    }
+                    // the codes are read off the comment rather than off the
+                    // trimmed body, so that each one keeps the range it was
+                    // written at — which is what a diagnostic about a single
+                    // code has to point at
+                    let (Some(open), Some(close)) = (comment.find('['), comment.rfind(']')) else {
                         continue;
                     };
-                    named
-                        .split(',')
-                        .map(|rule| rule.trim().to_compact_string())
-                        .filter(|rule| !rule.is_empty())
-                        .collect()
+                    codes(comment, open, close, construct.range.start())
                 }
             };
 
@@ -1038,26 +1265,196 @@ impl Suppressions {
             entries.push(Suppression {
                 line: line_of(source, construct.range.start()),
                 alone,
+                range: construct.range,
                 rules,
+                used: false,
             });
         }
 
         Self { entries }
     }
 
-    fn covers(&self, lint: &'static LintMetadata, line: OneIndexed) -> bool {
-        self.entries.iter().any(|suppression| {
-            let covered = suppression.line == line
-                || (suppression.alone && suppression.line.saturating_add(1) == line);
+    /// whether a comment silences `lint` on `line`, counting every one that does
+    /// as used
+    ///
+    /// every covering comment is counted rather than only the innermost: with two
+    /// of them silencing the same rule on the same line there is no saying which
+    /// one the writer meant to keep, and calling either unused would be a guess.
+    fn silences(&mut self, lint: &'static LintMetadata, line: OneIndexed) -> bool {
+        let mut silenced = false;
+
+        for suppression in &mut self.entries {
+            if !suppression.covers(line) {
+                continue;
+            }
 
-            covered
-                && (suppression.rules.is_empty()
-                    || suppression
-                        .rules
-                        .iter()
-                        .any(|rule| rule.as_str() == &*lint.name()))
-        })
+            if suppression.rules.is_empty() {
+                suppression.used = true;
+                silenced = true;
+                continue;
+            }
+
+            for rule in &mut suppression.rules {
+                if rule.name.as_str() == &*lint.name() {
+                    rule.used = true;
+                    silenced = true;
+                }
+            }
+        }
+
+        silenced
     }
+
+    /// the code that would silence an `unused-ignore-comment` reported on `line`
+    ///
+    /// only a code counts, never a blanket comment: a blanket `{# ty: ignore #}`
+    /// silencing its own unused report would silence every one of these. `naming`
+    /// is the code being reported, which cannot silence itself.
+    fn unused_silencer(&self, line: OneIndexed, reported: Reported) -> Option<Reported> {
+        self.entries
+            .iter()
+            .enumerate()
+            .filter(|(_, suppression)| suppression.covers(line))
+            .flat_map(|(entry, suppression)| {
+                suppression
+                    .rules
+                    .iter()
+                    .enumerate()
+                    .map(move |(code, rule)| {
+                        (
+                            Reported {
+                                entry,
+                                code: Some(code),
+                            },
+                            rule,
+                        )
+                    })
+            })
+            .find(|(candidate, rule)| {
+                rule.name.as_str() == &*UNUSED_IGNORE_COMMENT.name() && *candidate != reported
+            })
+            .map(|(candidate, _)| candidate)
+    }
+
+    /// whether the code `reported` names was counted used
+    fn is_used(&self, reported: Reported) -> bool {
+        let suppression = &self.entries[reported.entry];
+        match reported.code {
+            Some(code) => suppression.rules[code].used,
+            None => suppression.used,
+        }
+    }
+
+    fn mark_used(&mut self, reported: Reported) {
+        let suppression = &mut self.entries[reported.entry];
+        match reported.code {
+            Some(code) => suppression.rules[code].used = true,
+            None => suppression.used = true,
+        }
+    }
+}
+
+impl Suppression {
+    /// whether this comment applies to `line`
+    fn covers(&self, line: OneIndexed) -> bool {
+        self.line == line || (self.alone && self.line.saturating_add(1) == line)
+    }
+}
+
+/// what an `unused-ignore-comment` diagnostic is about: a whole comment, or one
+/// code inside it
+#[derive(Clone, Copy, Debug, Eq, PartialEq)]
+struct Reported {
+    entry: usize,
+    code: Option<usize>,
+}
+
+/// the codes written between `open` and `close` in `comment`, which starts at
+/// `start` in the source
+fn codes(comment: &str, open: usize, close: usize, start: TextSize) -> Vec<Rule> {
+    let mut rules = Vec::new();
+    let mut offset = open + 1;
+
+    for piece in comment[open + 1..close].split(',') {
+        let leading = piece.len() - piece.trim_start().len();
+        let name = piece.trim();
+
+        if !name.is_empty()
+            && let Ok(at) = TextSize::try_from(offset + leading)
+        {
+            rules.push(Rule {
+                name: name.to_compact_string(),
+                range: TextRange::at(start + at, TextSize::of(name)),
+                used: false,
+            });
+        }
+
+        offset += piece.len() + 1;
+    }
+
+    rules
+}
+
+/// take a whole suppression comment out
+///
+/// a comment with nothing else on its line takes the line with it, so that
+/// removing it doesn't leave a blank one behind.
+fn remove_comment_fix(source: &str, suppression: &Suppression) -> Fix {
+    let start = usize::from(suppression.range.start());
+    let end = usize::from(suppression.range.end());
+
+    let (start, end) = if suppression.alone {
+        let start = source[..start].rfind('\n').map_or(0, |index| index + 1);
+        let end = source[end..]
+            .find('\n')
+            .map_or(source.len(), |index| end + index + 1);
+        (start, end)
+    } else {
+        // the whitespace that separated the comment from what precedes it goes
+        // with it, so that no trailing space is left behind
+        (source[..start].trim_end().len(), end)
+    };
+
+    Fix::safe_edit(Edit::range_deletion(range_of(start, end)))
+}
+
+/// take one code out of a suppression comment, with the comma that separated it
+fn remove_code_fix(source: &str, suppression: &Suppression, code: usize) -> Fix {
+    let range = suppression.rules[code].range;
+    let limit = usize::from(suppression.range.end());
+    let start = usize::from(range.start());
+    let mut end = usize::from(range.end());
+
+    let trailing = source[end..limit]
+        .find(|character: char| !character.is_whitespace())
+        .unwrap_or(0);
+    if source[end + trailing..].starts_with(',') {
+        // the comma and the space after it go with the code, so that the codes
+        // left behind read as they were written
+        end += trailing + 1;
+        end += source[end..limit]
+            .find(|character: char| !character.is_whitespace())
+            .unwrap_or(0);
+        return Fix::safe_edit(Edit::range_deletion(range_of(start, end)));
+    }
+
+    // the last code carries the comma before it instead
+    let kept = source[..start].trim_end();
+    let start = kept.strip_suffix(',').map_or(start, |before| {
+        before
+            .trim_end_matches(|character: char| character.is_whitespace())
+            .len()
+    });
+
+    Fix::safe_edit(Edit::range_deletion(range_of(start, end)))
+}
+
+/// the range from `start` to `end`, which are byte offsets into a source
+fn range_of(start: usize, end: usize) -> TextRange {
+    let start = TextSize::try_from(start).unwrap_or_default();
+    let end = TextSize::try_from(end).unwrap_or_default();
+
+    TextRange::new(start.min(end), end)
 }
 
 /// the one-indexed line `offset` is on
@@ -1069,6 +1466,8 @@ fn line_of(source: &str, offset: TextSize) -> OneIndexed {
 mod tests {
     use ruff_text_size::Ranged;
 
+    use ty_python_semantic::lint::Level;
+
     use crate::django_template::tests::{DJANGO_BUILTINS, TemplateTest};
 
     /// a whole django project: a settings module the convention finds, an app
@@ -1078,7 +1477,12 @@ mod tests {
     /// `{% load static %}` and `{% load humanize %}` resolve — and what makes the
     /// indexes authoritative, which every check below depends on.
     fn project(template: &str) -> TemplateTest {
-        TemplateTest::with_site_packages(
+        project_with_rules(template, &[])
+    }
+
+    /// the same project, with some rules set to a level of their own
+    fn project_with_rules(template: &str, rules: &[(&str, Level)]) -> TemplateTest {
+        TemplateTest::with_rules(
             &[
                 (
                     "manage.py",
@@ -1256,6 +1660,7 @@ mod tests {
                     ",
                 ),
             ],
+            rules,
         )
     }
 
@@ -1868,8 +2273,11 @@ mod tests {
     fn a_suppression_naming_rules_silences_only_those() {
         assert_eq!(
             project("{# ty: ignore[unknown-template-filter] #}\n{% iff book %}\n").diagnostics(),
-            ["unknown-template-tag Error: no template tag named `iff` [iff]"],
-            "a rule the comment doesn't name is still reported"
+            [
+                "unused-ignore-comment Warning: unused `ty: ignore` directive [{# ty: ignore[unknown-template-filter] #}]",
+                "unknown-template-tag Error: no template tag named `iff` [iff]"
+            ],
+            "a rule the comment doesn't name is still reported, and the one it does name went unused"
         );
         assert!(
             project("{# ty: ignore[unknown-template-tag] #}\n{% iff book %}\n")
@@ -1882,10 +2290,196 @@ mod tests {
     fn a_suppression_with_something_beside_it_covers_only_its_own_line() {
         assert_eq!(
             project("a {# ty: ignore #}\n{% iff book %}\n").diagnostics(),
-            ["unknown-template-tag Error: no template tag named `iff` [iff]"]
+            [
+                "unused-ignore-comment Warning: unused blanket `ty: ignore` directive [{# ty: ignore #}]",
+                "unknown-template-tag Error: no template tag named `iff` [iff]"
+            ]
+        );
+    }
+
+    #[test]
+    fn a_suppression_that_silences_nothing_is_reported() {
+        assert_eq!(
+            project("{# ty: ignore[unknown-template-tag] #}\n<p>hello</p>\n").diagnostics(),
+            [
+                "unused-ignore-comment Warning: unused `ty: ignore` directive [{# ty: ignore[unknown-template-tag] #}]"
+            ]
+        );
+    }
+
+    #[test]
+    fn a_blanket_suppression_that_silences_nothing_is_reported() {
+        assert_eq!(
+            project("{# ty: ignore #}\n<p>hello</p>\n").diagnostics(),
+            [
+                "unused-ignore-comment Warning: unused blanket `ty: ignore` directive [{# ty: ignore #}]"
+            ]
+        );
+    }
+
+    #[test]
+    fn a_suppression_that_silences_something_is_not_reported() {
+        assert!(
+            project("{% iff book %} {# ty: ignore[unknown-template-tag] #}\n")
+                .diagnostics()
+                .is_empty()
+        );
+    }
+
+    #[test]
+    fn only_the_codes_of_a_suppression_that_went_unused_are_reported() {
+        assert_eq!(
+            project("{% iff book %} {# ty: ignore[unknown-template-tag, unresolved-route] #}\n")
+                .diagnostics(),
+            [
+                "unused-ignore-comment Warning: unused `ty: ignore` directive: `unresolved-route` [unresolved-route]"
+            ],
+            "the code that did the silencing is left alone"
         );
     }
 
+    #[test]
+    fn a_suppression_naming_a_rule_no_template_check_produces_is_left_alone() {
+        // nothing here looked for `division-by-zero`, so nothing here can say the
+        // comment went unused
+        assert!(
+            project("{# ty: ignore[division-by-zero] #}\n<p>hello</p>\n")
+                .diagnostics()
+                .is_empty()
+        );
+    }
+
+    #[test]
+    fn an_unused_suppression_is_itself_suppressible() {
+        assert!(
+            project(
+                "<p>hello</p> {# ty: ignore[unknown-template-tag] #} {# ty: ignore[unused-ignore-comment] #}\n"
+            )
+            .diagnostics()
+            .is_empty()
+        );
+    }
+
+    #[test]
+    fn a_suppression_for_the_unused_rule_cannot_silence_its_own_report() {
+        assert_eq!(
+            project("<p>hello</p> {# ty: ignore[unused-ignore-comment] #}\n").diagnostics(),
+            [
+                "unused-ignore-comment Warning: unused `ty: ignore` directive [{# ty: ignore[unused-ignore-comment] #}]"
+            ]
+        );
+    }
+
+    #[test]
+    fn a_blanket_suppression_does_not_silence_its_own_unused_report() {
+        assert_eq!(
+            project("<p>hello</p> {# ty: ignore #}\n").diagnostics(),
+            [
+                "unused-ignore-comment Warning: unused blanket `ty: ignore` directive [{# ty: ignore #}]"
+            ]
+        );
+    }
+
+    /// the template as every reported fix would leave it
+    fn fixed(template: &str) -> String {
+        let test = project(template);
+        let source = ruff_db::source::source_text(&test.db, test.file);
+        let mut fixed = source.to_string();
+
+        let diagnostics = crate::django_template::django_template_diagnostics(&test.db, test.file);
+        let mut edits: Vec<_> = diagnostics
+            .iter()
+            .filter_map(ruff_db::diagnostic::Diagnostic::fix)
+            .flat_map(ruff_diagnostics::Fix::edits)
+            .collect();
+        // back to front, so that an earlier edit's offsets still hold
+        edits.sort_by_key(|edit| std::cmp::Reverse(edit.start()));
+
+        for edit in edits {
+            fixed.replace_range(
+                usize::from(edit.start())..usize::from(edit.end()),
+                edit.content().unwrap_or_default(),
+            );
+        }
+
+        fixed
+    }
+
+    #[test]
+    fn the_fix_takes_out_what_went_unused() {
+        assert_eq!(
+            fixed("{# ty: ignore[unknown-template-tag] #}\n<p>hello</p>\n"),
+            "<p>hello</p>\n",
+            "a comment with nothing else on its line takes the line with it"
+        );
+        assert_eq!(fixed("<p>hello</p> {# ty: ignore #}\n"), "<p>hello</p>\n");
+        assert_eq!(
+            fixed("{{ x|nope }} {# ty: ignore[unresolved-route, unknown-template-filter] #}\n"),
+            "{{ x|nope }} {# ty: ignore[unknown-template-filter] #}\n",
+            "only the code that went unused, and the comma after it"
+        );
+        assert_eq!(
+            fixed("{{ x|nope }} {# ty: ignore[unknown-template-filter, unresolved-route] #}\n"),
+            "{{ x|nope }} {# ty: ignore[unknown-template-filter] #}\n",
+            "the last code carries the comma before it instead"
+        );
+    }
+
+    #[test]
+    fn a_code_beside_the_unused_rule_silences_the_whole_comment() {
+        // what a python file does for `# ty: ignore[division-by-zero,
+        // unused-ignore-comment]`: the second code silences the first's report,
+        // and is used up doing it
+        assert!(
+            project("<p>hello</p> {# ty: ignore[unknown-template-tag, unused-ignore-comment] #}\n")
+                .diagnostics()
+                .is_empty()
+        );
+    }
+
+    #[test]
+    fn a_suppression_for_a_rule_configuration_turned_off_is_reported() {
+        // the same as a python file: the check never runs, so the comment never
+        // silences anything, so it is unused. see the `ty: ignore` suppression
+        // tests under `crates/ty_python_semantic/resources/mdtest/suppressions`
+        let test = project_with_rules(
+            "{% iff book %} {# ty: ignore[unknown-template-tag] #}\n",
+            &[("unknown-template-tag", Level::Ignore)],
+        );
+
+        assert_eq!(
+            test.diagnostics(),
+            [
+                "unused-ignore-comment Warning: unused `ty: ignore` directive [{# ty: ignore[unknown-template-tag] #}]"
+            ]
+        );
+    }
+
+    #[test]
+    fn nothing_is_reported_where_the_unused_rule_is_turned_off() {
+        let test = project_with_rules(
+            "<p>hello</p> {# ty: ignore[unknown-template-tag] #}\n",
+            &[("unused-ignore-comment", Level::Ignore)],
+        );
+
+        assert!(test.diagnostics().is_empty());
+    }
+
+    #[test]
+    fn a_suppression_is_not_reported_unused_where_a_check_could_not_answer() {
+        // no `manage.py`, so no check decided anything about this file — see
+        // `a_project_whose_settings_cannot_be_read_reports_nothing_it_would_have_to_guess`
+        let test = TemplateTest::new(&[
+            ("blog/__init__.py", ""),
+            (
+                "blog/templates/blog/post.html",
+                "{# ty: ignore[unknown-template-tag] #}\n{# ty: ignore #}\n",
+            ),
+        ]);
+
+        assert!(test.diagnostics().is_empty());
+    }
+
     #[test]
     fn a_project_whose_settings_cannot_be_read_reports_nothing_it_would_have_to_guess() {
         // no `manage.py`, so no `INSTALLED_APPS` — and without those there is no
diff --git a/docs/basedpython/frameworks/django-templates.md b/docs/basedpython/frameworks/django-templates.md
index cd44076fa2..4afd1d4205 100644
--- a/docs/basedpython/frameworks/django-templates.md
+++ b/docs/basedpython/frameworks/django-templates.md
@@ -76,6 +76,8 @@ a `{% for book in shelf %}` shows the element type it binds, which is what says
 
 **diagnostics.** a template reports twelve rules — an unclosed block, an unknown tag or filter, a tag used without its `{% load %}`, a missing template or static file, an unknown route or the wrong arguments to one, a block no ancestor declares, and a member django cannot call. each is silent unless the index behind it is authoritative, so a project whose settings cannot be read reports nothing rather than guessing. silence one with `{# ty: ignore #}` or `{# ty: ignore[rule-name] #}`, or configure it under `[tool.ty.rules]` like any other.
 
+a comment that silenced nothing is reported as `unused-ignore-comment`, the same rule a stale `# ty: ignore` raises in a python file, so a suppression left behind by a fix doesn't sit there unnoticed. the one thing a template adds is that a check reporting nothing because its index was not authoritative has decided nothing, and a comment naming that rule is left alone rather than called unused.
+
 `by check` reports them too. a template is not in the project's python file set and is never read as python — it is checked as the template it is — but it is part of the project, so the command line and the editor say the same thing about the same file. only the project's own templates are checked; an installed app's are a dependency's source, and a project with no django has no django templates.
 
 an unknown *variable* is still not reported: a context can come from places a scan cannot see, so absence is not evidence.

From 7a64aaeb2052ffc10390ff7b20051a3ff1d73c0f Mon Sep 17 00:00:00 2001
From: KotlinIsland <65446343+kotlinisland@users.noreply.github.com>
Date: Sat, 8 Aug 2026 21:38:32 +1000
Subject: [PATCH 14/16] django's `__` lookups written as expressions
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

`filter(author.name == "Ursula", published > date(1970, 1, 1))` lowers to the
keywords it spells, and a json subscript is a key or index transform
(`data["key"]` → `data__key`, `data[0]` → `data__0`). verified by sql
equivalence against real django rather than by reading the output

the classifier is one query shared by ty and the transpiler, so they cannot
disagree about what a path means. `!=` refuses, because django spells it
`.exclude()`/`~Q()` and that changes which method is called; a key colliding with
a lookup name refuses, because `data__gt` compiles to `data > 1` rather than the
key `"gt"`

the gate that gives an otherwise-unresolvable name a meaning now has one home,
shared with enum members and implicit receivers — they observably disagreed about
exactly one name. and a lookup path is not an undefined name to the linter
---
 .../src/transforms/ast_driver.rs              |  26 +-
 .../src/transforms/django_lookup.rs           |  83 +++
 crates/by_transforms/src/transforms/mod.rs    |   1 +
 crates/by_transforms/src/type_info.rs         |  17 +
 .../fixtures/pyflakes/F821_basedpython.by     |  22 +
 ...akes__tests__F821_F821_basedpython.by.snap |  40 ++
 crates/ruff_python_semantic/src/model.rs      |  66 ++
 crates/ty/tests/django_lookup_runtime.rs      | 323 ++++++++++
 .../mdtest/basedpython_context_sensitive.md   |  42 ++
 .../mdtest/basedpython_implicit_receiver.md   |  22 +
 .../resources/mdtest/external/django.md       | 364 +++++++++++
 crates/ty_python_semantic/src/lib.rs          |   5 +-
 .../ty_python_semantic/src/semantic_model.rs  |  43 +-
 crates/ty_python_semantic/src/types.rs        |   3 +-
 .../src/types/context_sensitive.rs            |  34 +-
 .../src/types/dedicated/django.rs             | 593 +++++++++++++++++-
 .../src/types/dedicated/mod.rs                |   2 +-
 .../src/types/infer/builder.rs                | 104 ++-
 .../src/types/name_fallback.rs                | 143 +++++
 .../ty_python_semantic/src/types/receivers.rs |  45 +-
 docs/basedpython/frameworks/django.md         |  63 ++
 21 files changed, 1956 insertions(+), 85 deletions(-)
 create mode 100644 crates/by_transforms/src/transforms/django_lookup.rs
 create mode 100644 crates/ty/tests/django_lookup_runtime.rs
 create mode 100644 crates/ty_python_semantic/src/types/name_fallback.rs

diff --git a/crates/by_transforms/src/transforms/ast_driver.rs b/crates/by_transforms/src/transforms/ast_driver.rs
index f997a6930e..301d0637e0 100644
--- a/crates/by_transforms/src/transforms/ast_driver.rs
+++ b/crates/by_transforms/src/transforms/ast_driver.rs
@@ -36,16 +36,16 @@ use ruff_text_size::{Ranged, TextRange};
 use super::{
     annotation, anon_named_tuple, auto_quote, callable, character_type, checked_cast, coalesce,
     coalesce_chain, compat, context_params, conversion, decl_site_variance, decorator_keyword,
-    dedent_string, destructure, dynamic_keyword, empty_declarations, export_import, extension,
-    float_const, force_unwrap, frameworks, generic_call, generics, grapheme_string, identity_swap,
-    if_let, implementation, implicit_receiver, implicit_typing, inferred_annotation, init_method,
-    just_float, kw_subscript, literal_string, literal_types, local_once, main_function, match_type,
-    modifiers, mutable_defaults, none_chain, optional_type, overload, parametric_is, postfix_await,
-    propagate, properties, protocol_type, raises_clause, reified_generic, repeated_underscore,
-    sentinel, some_ctor, soundness, statement_expression, string_tag, super_keyword,
-    symbolic_type_op, top_star, trailing_lambda, tuple_index, type_fn, type_is, type_reification,
-    typed_dict_literal, typed_lambda, typeof_keyword, unique_loop_bindings, unpack,
-    use_site_variance,
+    dedent_string, destructure, django_lookup, dynamic_keyword, empty_declarations, export_import,
+    extension, float_const, force_unwrap, frameworks, generic_call, generics, grapheme_string,
+    identity_swap, if_let, implementation, implicit_receiver, implicit_typing, inferred_annotation,
+    init_method, just_float, kw_subscript, literal_string, literal_types, local_once,
+    main_function, match_type, modifiers, mutable_defaults, none_chain, optional_type, overload,
+    parametric_is, postfix_await, propagate, properties, protocol_type, raises_clause,
+    reified_generic, repeated_underscore, sentinel, some_ctor, soundness, statement_expression,
+    string_tag, super_keyword, symbolic_type_op, top_star, trailing_lambda, tuple_index, type_fn,
+    type_is, type_reification, typed_dict_literal, typed_lambda, typeof_keyword,
+    unique_loop_bindings, unpack, use_site_variance,
 };
 use crate::Config;
 use crate::type_info::TypeInfo;
@@ -555,6 +555,7 @@ pub(crate) fn run_against_source<'a>(
     let implementation_block_pass = implementation::ImplementationBlockPass::new(source_ref);
     let conversion_pass = conversion::ConversionPass::new(source_ref);
     let implicit_receiver_pass = implicit_receiver::ImplicitReceiverPass;
+    let django_lookup_pass = django_lookup::DjangoLookupPass;
     let frameworks_pass = frameworks::FrameworksPass::new(source_ref);
     let variance_pass = decl_site_variance::VarianceStripPass::new(source_ref);
     let anon_named_tuple_pass =
@@ -698,6 +699,11 @@ pub(crate) fn run_against_source<'a>(
         // members → its receiver parameter. same shape as the extension rewrite
         // above, which wins when both could apply
         &implicit_receiver_pass,
+        // django lookups written as expressions (`filter(author.name == "x")`)
+        // become keyword arguments. the argument is replaced whole, with the
+        // value passing through as `Src`, so lowerings inside it still compose;
+        // disjoint from the call rewrites above, which target the callee
+        &django_lookup_pass,
         &dynamic_keyword_pass,
         // import-only companion to the ty-side implicit `Character` resolution;
         // emits no text edits, so ordering among the type passes is free
diff --git a/crates/by_transforms/src/transforms/django_lookup.rs b/crates/by_transforms/src/transforms/django_lookup.rs
new file mode 100644
index 0000000000..aa90866965
--- /dev/null
+++ b/crates/by_transforms/src/transforms/django_lookup.rs
@@ -0,0 +1,83 @@
+//! Lowering for django lookups written as expressions.
+//!
+//! `Book.objects.filter(author.name == "Ursula", published > date(1970, 1, 1))`
+//! lowers to `Book.objects.filter(author__name="Ursula",
+//! published__gt=date(1970, 1, 1))`.
+//!
+//! Which arguments are lookups is ty's answer, not this pass's: the names in a
+//! lookup path resolve to model fields rather than to anything in scope, and the
+//! checker and the lowering read that from one query, so the query the file was
+//! checked against is the query it lowers to. Every argument ty did not read as
+//! a lookup passes through untouched.
+//!
+//! The value is re-emitted as a source span, so lowerings inside it still apply.
+
+use ruff_python_ast::visitor::{Visitor, walk_expr};
+use ruff_python_ast::{Expr, Stmt};
+
+use super::ast_driver::{Fragment, PassContext, TypeAwarePass};
+use crate::type_info::TypeInfo;
+
+struct DjangoLookupLower<'a> {
+    types: &'a dyn TypeInfo,
+    edits: Vec<(ruff_text_size::TextRange, Vec<Fragment>)>,
+}
+
+impl<'ast> Visitor<'ast> for DjangoLookupLower<'_> {
+    fn visit_expr(&mut self, expr: &'ast Expr) {
+        if let Expr::Call(call) = expr {
+            for lookup in self.types.django_lookup_arguments(call) {
+                self.edits.push((
+                    lookup.argument,
+                    vec![
+                        Fragment::Lit(format!("{}=", lookup.key)),
+                        Fragment::Src(lookup.value),
+                    ],
+                ));
+            }
+        }
+        walk_expr(self, expr);
+    }
+}
+
+pub(crate) struct DjangoLookupPass;
+
+impl TypeAwarePass for DjangoLookupPass {
+    fn run(&self, stmts: &[Stmt], types: &dyn TypeInfo, ctx: &mut PassContext) {
+        let mut inner = DjangoLookupLower {
+            types,
+            edits: Vec::new(),
+        };
+        for stmt in stmts {
+            inner.visit_stmt(stmt);
+        }
+        ctx.template_edits.extend(inner.edits);
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use indoc::indoc;
+
+    use crate::{Config, transpile};
+
+    /// A file with no django in it must come out untouched. The lowering is
+    /// keyed entirely on ty resolving the callee to a lookup method on a model,
+    /// so a comparison argument to any other call is an ordinary argument —
+    /// which is what makes the rewrite additive rather than a rule about the
+    /// word `filter`.
+    #[test]
+    fn a_comparison_argument_to_an_ordinary_call_is_untouched() {
+        for source in [
+            "def filter(*args): ...\nfilter(1 == 2)\n",
+            "class M:\n    def filter(self, *args): ...\n\nM().filter(1 == 2)\n",
+            indoc! {"
+                def use(objects) -> None:
+                    objects.filter(objects == 1)
+            "},
+        ] {
+            let out = transpile(source, &Config::test_default()).expect("transpile should succeed");
+            assert!(out.contains("== "), "for `{source}` got:\n{out}");
+        }
+    }
+}
diff --git a/crates/by_transforms/src/transforms/mod.rs b/crates/by_transforms/src/transforms/mod.rs
index 06ae738382..bf93d481f9 100644
--- a/crates/by_transforms/src/transforms/mod.rs
+++ b/crates/by_transforms/src/transforms/mod.rs
@@ -15,6 +15,7 @@ pub(crate) mod decl_site_variance;
 pub(crate) mod decorator_keyword;
 pub(crate) mod dedent_string;
 pub(crate) mod destructure;
+pub(crate) mod django_lookup;
 pub(crate) mod dynamic_keyword;
 pub(crate) mod empty_declarations;
 pub(crate) mod enums;
diff --git a/crates/by_transforms/src/type_info.rs b/crates/by_transforms/src/type_info.rs
index 97876115c4..80333f071c 100644
--- a/crates/by_transforms/src/type_info.rs
+++ b/crates/by_transforms/src/type_info.rs
@@ -181,6 +181,16 @@ pub(crate) trait TypeInfo {
     /// it used unqualified. both lower to the block's receiver parameter
     fn implicit_receiver_name(&self, name: &ExprName) -> Option<ImplicitReceiverReference>;
 
+    /// how each positional argument of a django lookup method that spells a
+    /// `__` lookup as an expression lowers to a keyword —
+    /// `filter(author.name == "x")` → `filter(author__name="x")`. empty for
+    /// every other call, and for any argument the checker did not read as a
+    /// lookup, which must then be left exactly as written
+    fn django_lookup_arguments(
+        &self,
+        call: &ruff_python_ast::ExprCall,
+    ) -> Vec<ty_python_semantic::DjangoLookupArgument>;
+
     /// the enum a *context-sensitively* resolved name must be qualified with —
     /// `Red` in a `Color` context lowers to `Color.Red`. `None` for every name
     /// that resolves the ordinary way
@@ -587,6 +597,13 @@ impl TypeInfo for SemanticModel<'_> {
         SemanticModel::implicit_receiver_name(self, name)
     }
 
+    fn django_lookup_arguments(
+        &self,
+        call: &ruff_python_ast::ExprCall,
+    ) -> Vec<ty_python_semantic::DjangoLookupArgument> {
+        SemanticModel::django_lookup_arguments(self, call)
+    }
+
     fn context_sensitive_qualifier(&self, name: &ExprName) -> Option<String> {
         SemanticModel::context_sensitive_qualifier(self, name)
     }
diff --git a/crates/ruff_linter/resources/test/fixtures/pyflakes/F821_basedpython.by b/crates/ruff_linter/resources/test/fixtures/pyflakes/F821_basedpython.by
index b3c0d796c6..8202da0c4b 100644
--- a/crates/ruff_linter/resources/test/fixtures/pyflakes/F821_basedpython.by
+++ b/crates/ruff_linter/resources/test/fixtures/pyflakes/F821_basedpython.by
@@ -192,3 +192,25 @@ print(ImplementedAsInterface(Implemented()))
 # check` reports it as an unresolved type
 implementation UndefinedInterface for UndefinedImplemented:  # F821
     pass
+
+
+# a django lookup expression: the transpiler lowers the field path to the
+# keyword it spells (`filter(author.name == "x")` -> `filter(author__name="x")`),
+# so the path is never evaluated and none of these names is undefined
+class Model:
+    objects: object
+
+
+Book = Model()
+Book.objects.filter(author.name == "Ursula")
+Book.objects.filter(published > 1)
+Book.objects.filter(data["key"] == 1)
+Book.objects.exclude(title == "x", author.pk >= 3)
+Book.objects.filter(pk in [1, 2, 3])
+Book.objects.get(pk == 1)
+
+# but the suppression is only for that shape, so each of these is still reported
+Book.objects.filter(bare_name)  # F821
+Book.objects.annotate(not_a_lookup_method.x == 1)  # F821
+Book.objects.filter(data[undefined_index] == 1)  # F821
+Book.objects.filter(no_lookup_for_ne != 1)  # F821
diff --git a/crates/ruff_linter/src/rules/pyflakes/snapshots/ruff_linter__rules__pyflakes__tests__F821_F821_basedpython.by.snap b/crates/ruff_linter/src/rules/pyflakes/snapshots/ruff_linter__rules__pyflakes__tests__F821_F821_basedpython.by.snap
index ea01903560..4e991368cb 100644
--- a/crates/ruff_linter/src/rules/pyflakes/snapshots/ruff_linter__rules__pyflakes__tests__F821_F821_basedpython.by.snap
+++ b/crates/ruff_linter/src/rules/pyflakes/snapshots/ruff_linter__rules__pyflakes__tests__F821_F821_basedpython.by.snap
@@ -176,3 +176,43 @@ F821 Undefined name `UndefinedInterface`
     |                ^^^^^^^^^^^^^^^^^^
 194 |     pass
     |
+
+F821 Undefined name `bare_name`
+   --> F821_basedpython.by:213:21
+    |
+212 | # but the suppression is only for that shape, so each of these is still reported
+213 | Book.objects.filter(bare_name)  # F821
+    |                     ^^^^^^^^^
+214 | Book.objects.annotate(not_a_lookup_method.x == 1)  # F821
+215 | Book.objects.filter(data[undefined_index] == 1)  # F821
+    |
+
+F821 Undefined name `not_a_lookup_method`
+   --> F821_basedpython.by:214:23
+    |
+212 | # but the suppression is only for that shape, so each of these is still reported
+213 | Book.objects.filter(bare_name)  # F821
+214 | Book.objects.annotate(not_a_lookup_method.x == 1)  # F821
+    |                       ^^^^^^^^^^^^^^^^^^^
+215 | Book.objects.filter(data[undefined_index] == 1)  # F821
+216 | Book.objects.filter(no_lookup_for_ne != 1)  # F821
+    |
+
+F821 Undefined name `undefined_index`
+   --> F821_basedpython.by:215:26
+    |
+213 | Book.objects.filter(bare_name)  # F821
+214 | Book.objects.annotate(not_a_lookup_method.x == 1)  # F821
+215 | Book.objects.filter(data[undefined_index] == 1)  # F821
+    |                          ^^^^^^^^^^^^^^^
+216 | Book.objects.filter(no_lookup_for_ne != 1)  # F821
+    |
+
+F821 Undefined name `no_lookup_for_ne`
+   --> F821_basedpython.by:216:21
+    |
+214 | Book.objects.annotate(not_a_lookup_method.x == 1)  # F821
+215 | Book.objects.filter(data[undefined_index] == 1)  # F821
+216 | Book.objects.filter(no_lookup_for_ne != 1)  # F821
+    |                     ^^^^^^^^^^^^^^^^
+    |
diff --git a/crates/ruff_python_semantic/src/model.rs b/crates/ruff_python_semantic/src/model.rs
index 0665709a72..b5a2a10934 100644
--- a/crates/ruff_python_semantic/src/model.rs
+++ b/crates/ruff_python_semantic/src/model.rs
@@ -785,6 +785,7 @@ impl<'a> SemanticModel<'a> {
         } else if self.is_basedpython_class_base_self_ref(name)
             || self.is_basedpython_transpile_resolved_name(name)
             || self.is_basedpython_type_is_lhs(name)
+            || self.is_basedpython_django_lookup_path(name)
         {
             // basedpython resolves these forms at transpile time, so the name is
             // not actually undefined at runtime
@@ -896,6 +897,71 @@ impl<'a> SemanticModel<'a> {
         matches!(compare.left.as_ref(), Expr::Name(left) if left.range == name.range)
     }
 
+    /// True if `name` leads the field path of a django lookup expression —
+    /// `filter(author.name == "x")`, which the transpiler lowers to the keyword
+    /// `author__name="x"`, so the path is never evaluated at runtime.
+    ///
+    /// This is deliberately syntactic, and deliberately broader than the
+    /// transpiler's own rule: whether the leading segment really names a field
+    /// of the model is a question only the type checker can answer, and it does
+    /// answer it. Reporting an unresolvable path there rather than here keeps
+    /// one answer to it instead of two that can disagree.
+    fn is_basedpython_django_lookup_path(&self, name: &ast::ExprName) -> bool {
+        if !self.in_basedpython_file() {
+            return false;
+        }
+        let mut ancestors = self.current_expressions().skip(1);
+
+        // climb the attribute / subscript chain the name leads. the name has to
+        // *lead* it — in `data[key]`, `key` is the index, not the path
+        let mut path = name.range;
+        let mut parent = ancestors.next();
+        while let Some(expr) = parent {
+            let value = match expr {
+                Expr::Attribute(attribute) => attribute.value.range(),
+                Expr::Subscript(subscript) => subscript.value.range(),
+                _ => break,
+            };
+            if value != path {
+                break;
+            }
+            path = expr.range();
+            parent = ancestors.next();
+        }
+
+        // the path must be the left operand of one comparison django can spell
+        let Some(Expr::Compare(compare)) = parent else {
+            return false;
+        };
+        if compare.left.range() != path
+            || !matches!(
+                compare.ops.as_ref(),
+                [ast::CmpOp::Eq
+                    | ast::CmpOp::Gt
+                    | ast::CmpOp::GtE
+                    | ast::CmpOp::Lt
+                    | ast::CmpOp::LtE
+                    | ast::CmpOp::In]
+            )
+        {
+            return false;
+        }
+
+        // and that comparison must be a positional argument of a lookup method
+        let Some(Expr::Call(call)) = ancestors.next() else {
+            return false;
+        };
+        let Expr::Attribute(func) = call.func.as_ref() else {
+            return false;
+        };
+        matches!(func.attr.as_str(), "filter" | "exclude" | "get" | "aget")
+            && call
+                .arguments
+                .args
+                .iter()
+                .any(|argument| argument.range() == compare.range())
+    }
+
     /// True if `name` is a forward self-reference that the basedpython
     /// transpiler will auto-quote, so resolution should not flag it as
     /// undefined. This covers two positions:
diff --git a/crates/ty/tests/django_lookup_runtime.rs b/crates/ty/tests/django_lookup_runtime.rs
new file mode 100644
index 0000000000..dcdf4b49d6
--- /dev/null
+++ b/crates/ty/tests/django_lookup_runtime.rs
@@ -0,0 +1,323 @@
+//! runtime half of the django lookup-expression contract.
+//!
+//! `filter(author.name == "x")` lowers to `filter(author__name="x")`, and what
+//! matters is not the text but what django is handed: the right keyword names,
+//! the right values, once each. this transpiles a project against a minimal
+//! django whose manager records the keywords it receives, executes the output,
+//! and asserts on the record.
+//!
+//! the recorded keywords are the same ones a real django builds its SQL from —
+//! `docs/basedpython/frameworks/django.md` covers the query each spells.
+
+use std::fs;
+use std::path::Path;
+use std::process::Command;
+
+/// a django small enough to read and complete enough for both halves: ty
+/// recognizes the model, the fields and the manager from it (the `KnownClass`
+/// names have to be *defined* in django's own module paths, on a third-party
+/// search path, hence the site-packages layout), and it runs, recording the
+/// keywords a lookup call is handed
+const MOCK_DJANGO: &[(&str, &str)] = &[
+    ("django/__init__.py", ""),
+    // `from django.db import models` reads `models` as an attribute of the
+    // package, which only exists once the submodule is imported
+    (
+        "django/db/__init__.py",
+        "from django.db import models as models\n",
+    ),
+    (
+        "django/db/models/__init__.py",
+        "from django.db.models.base import Model as Model\n\
+         from django.db.models.fields import CharField as CharField, DateField as DateField\n\
+         from django.db.models.fields.json import JSONField as JSONField\n\
+         from django.db.models.fields.related import CASCADE as CASCADE, ForeignKey as ForeignKey\n\
+         from django.db.models.manager import Manager as Manager\n\
+         from django.db.models.query import Q as Q, QuerySet as QuerySet\n",
+    ),
+    (
+        "django/db/models/base.py",
+        "from typing import Any, ClassVar, Self\n\
+         \n\
+         from django.db.models.manager import Manager\n\
+         \n\
+         \n\
+         class Model:\n\
+         \x20   objects: ClassVar[Manager[Self]]\n\
+         \x20   pk: Any\n\
+         \n\
+         \x20   def __init_subclass__(cls, **kwargs: Any) -> None:\n\
+         \x20       super().__init_subclass__(**kwargs)\n\
+         \x20       cls.objects = Manager()\n",
+    ),
+    (
+        "django/db/models/manager.py",
+        "from typing import Any\n\
+         \n\
+         from django.db.models.query import QuerySet\n\
+         \n\
+         \n\
+         class BaseManager[_M]:\n\
+         \x20   def filter(self, *args: Any, **kwargs: Any) -> QuerySet[_M, _M]:\n\
+         \x20       return QuerySet(kwargs)\n\
+         \n\
+         \x20   def exclude(self, *args: Any, **kwargs: Any) -> QuerySet[_M, _M]:\n\
+         \x20       return QuerySet(kwargs)\n\
+         \n\
+         \n\
+         class Manager[_M](BaseManager[_M]):\n\
+         \x20   pass\n",
+    ),
+    (
+        "django/db/models/query.py",
+        "from typing import Any\n\
+         \n\
+         \n\
+         class Q:\n\
+         \x20   def __init__(self, **kwargs: Any) -> None: ...\n\
+         \n\
+         \n\
+         class QuerySet[_M, _Row = _M]:\n\
+         \x20   def __init__(self, recorded: dict[str, Any] | None = None) -> None:\n\
+         \x20       self.recorded = recorded or {}\n",
+    ),
+    (
+        "django/db/models/fields/__init__.py",
+        "from typing import Any\n\
+         \n\
+         \n\
+         class Field[_ST, _GT]:\n\
+         \x20   _pyi_private_set_type: Any\n\
+         \x20   _pyi_private_get_type: Any\n\
+         \n\
+         \x20   def __init__(self, **kwargs: Any) -> None: ...\n\
+         \x20   def __get__(self, instance: Any, owner: Any = None) -> _GT: ...\n\
+         \x20   def __set__(self, instance: Any, value: _ST) -> None: ...\n\
+         \n\
+         \n\
+         class CharField[_ST, _GT](Field[_ST, _GT]):\n\
+         \x20   _pyi_private_set_type: str\n\
+         \x20   _pyi_private_get_type: str\n\
+         \n\
+         \n\
+         class DateField[_ST, _GT](Field[_ST, _GT]):\n\
+         \x20   _pyi_private_set_type: Any\n\
+         \x20   _pyi_private_get_type: Any\n",
+    ),
+    // the key/index transforms live on `JSONField`, which is recognized by the
+    // module it is declared in, so the mock has to declare it in that module too
+    (
+        "django/db/models/fields/json.py",
+        "from typing import Any\n\
+         \n\
+         from django.db.models.fields import Field\n\
+         \n\
+         \n\
+         class JSONField[_ST, _GT](Field[_ST, _GT]):\n\
+         \x20   _pyi_private_set_type: Any\n\
+         \x20   _pyi_private_get_type: Any\n",
+    ),
+    (
+        "django/db/models/fields/related.py",
+        "from typing import Any\n\
+         \n\
+         from django.db.models.fields import Field\n\
+         \n\
+         CASCADE = \"cascade\"\n\
+         \n\
+         \n\
+         class ForeignKey[_ST, _GT](Field[_ST, _GT]):\n\
+         \x20   _pyi_private_set_type: Any\n\
+         \x20   _pyi_private_get_type: Any\n\
+         \n\
+         \x20   def __init__(self, to: Any, on_delete: Any = None, **kwargs: Any) -> None: ...\n",
+    ),
+];
+
+const MODELS: &str = "\
+from django.db import models
+
+
+class Author(models.Model):
+    name = models.CharField(max_length=100)
+
+
+class Book(models.Model):
+    title = models.CharField(max_length=100)
+    author = models.ForeignKey(Author, on_delete=models.CASCADE)
+
+
+class Doc(models.Model):
+    name = models.CharField(max_length=100)
+    data = models.JSONField()
+";
+
+const MAIN: &str = r#"
+from django.db.models import Q
+
+from models import Book, Doc
+
+
+def label(name, queryset):
+    print(name, sorted(queryset.recorded.items()))
+
+
+calls = 0
+
+
+def once(value):
+    global calls
+    calls += 1
+    return value
+
+
+label("exact", Book.objects.filter(title == "Left Hand"))
+label("relation", Book.objects.filter(author.name == "Ursula"))
+label("pk", Book.objects.filter(pk == 1))
+label("membership", Book.objects.filter(title in ["a", "b"]))
+label("combined", Book.objects.filter(author.name == "Ursula", title == "Left Hand"))
+label("excluded", Book.objects.exclude(title == "x"))
+label("after positional", Book.objects.filter(Q(), title == "x"))
+label("beside keyword", Book.objects.filter(title == "a", author__name="b"))
+label("evaluated once", Book.objects.filter(title == once("v")))
+label("json key", Doc.objects.filter(data["key"] == 1))
+label("json nested", Doc.objects.filter(data["a"]["b"] == 1))
+label("json index", Doc.objects.filter(data[0] == 1))
+label("json key operator", Doc.objects.filter(data["key"] > 1))
+label("json key and field", Doc.objects.filter(name == "n", data["key"] == 1))
+print("calls", calls)
+"#;
+
+/// a CPython 3.13, provisioned through uv the way the divergence harness does:
+/// the mock django uses pep 695 generics and pep 696 defaults, whose runtime
+/// floor is 3.13
+#[cfg(not(windows))]
+fn python() -> Option<String> {
+    if let Ok(path) = std::env::var("PYTHON") {
+        return Some(path);
+    }
+    let find = || {
+        let output = Command::new("uv")
+            .args(["python", "find", "3.13"])
+            .output()
+            .ok()?;
+        output
+            .status
+            .success()
+            .then(|| String::from_utf8_lossy(&output.stdout).trim().to_owned())
+    };
+    if let Some(path) = find() {
+        return Some(path);
+    }
+    Command::new("uv")
+        .args(["python", "install", "3.13"])
+        .output()
+        .ok()?;
+    find()
+}
+
+#[cfg(windows)]
+fn python() -> Option<String> {
+    std::env::var("PYTHON").ok()
+}
+
+fn write(root: &Path, relative: &str, contents: &str) {
+    let path = root.join(relative);
+    fs::create_dir_all(path.parent().expect("a relative path has a parent")).expect("create dir");
+    fs::write(path, contents).expect("write file");
+}
+
+fn transpile(project: &Path, module: &str) -> String {
+    let output = Command::new(env!("CARGO_BIN_EXE_by"))
+        .args(["transpile", module])
+        .current_dir(project)
+        .output()
+        .expect("failed to spawn by");
+    assert!(
+        output.status.success(),
+        "by transpile {module} failed:\n{}",
+        String::from_utf8_lossy(&output.stderr)
+    );
+    String::from_utf8(output.stdout).expect("transpiled output is utf-8")
+}
+
+#[test]
+#[expect(
+    clippy::print_stderr,
+    reason = "a skipped test must say why it skipped, or it reads as a pass"
+)]
+fn lookup_expressions_hand_django_the_keywords_they_spell() {
+    let Some(python) = python() else {
+        eprintln!(
+            "skipping django lookup runtime test: no python 3.13 found \
+             (set PYTHON to one, or make `uv` available)"
+        );
+        return;
+    };
+
+    let project = tempfile::tempdir().expect("tempdir");
+    let root = project.path();
+    // ty only reads django's `KnownClass` names off a third-party search path,
+    // so the mock lives in a venv's site-packages rather than beside the source
+    let site_packages = "\
+.venv/lib/python3.13/site-packages";
+    for (relative, contents) in MOCK_DJANGO {
+        write(root, &format!("{site_packages}/{relative}"), contents);
+    }
+    write(
+        root,
+        ".venv/pyvenv.cfg",
+        "home = /usr/bin\nversion = 3.13.0\n",
+    );
+    write(
+        root,
+        "pyproject.toml",
+        "[project]\nname = \"probe\"\nversion = \"0\"\nrequires-python = \">=3.13\"\n\n\
+         [tool.ty.environment]\npython = \".venv\"\npython-version = \"3.13\"\n",
+    );
+    write(root, "models.by", MODELS);
+    write(root, "main.by", MAIN);
+
+    let lowered = project.path().join("lowered");
+    fs::create_dir_all(&lowered).expect("create dir");
+    for module in ["models", "main"] {
+        fs::write(
+            lowered.join(format!("{module}.py")),
+            transpile(root, &format!("{module}.by")),
+        )
+        .expect("write lowered module");
+    }
+
+    let output = Command::new(&python)
+        .arg("main.py")
+        .current_dir(&lowered)
+        .env("PYTHONPATH", root.join(site_packages).as_os_str())
+        .output()
+        .expect("failed to spawn python");
+    assert!(
+        output.status.success(),
+        "lowered program failed:\n--- stdout ---\n{}\n--- stderr ---\n{}",
+        String::from_utf8_lossy(&output.stdout),
+        String::from_utf8_lossy(&output.stderr),
+    );
+
+    assert_eq!(
+        String::from_utf8_lossy(&output.stdout).trim(),
+        "\
+exact [('title', 'Left Hand')]
+relation [('author__name', 'Ursula')]
+pk [('pk', 1)]
+membership [('title__in', ['a', 'b'])]
+combined [('author__name', 'Ursula'), ('title', 'Left Hand')]
+excluded [('title', 'x')]
+after positional [('title', 'x')]
+beside keyword [('author__name', 'b'), ('title', 'a')]
+evaluated once [('title', 'v')]
+json key [('data__key', 1)]
+json nested [('data__a__b', 1)]
+json index [('data__0', 1)]
+json key operator [('data__key__gt', 1)]
+json key and field [('data__key', 1), ('name', 'n')]
+calls 1"
+    );
+}
diff --git a/crates/ty_python_semantic/resources/mdtest/basedpython_context_sensitive.md b/crates/ty_python_semantic/resources/mdtest/basedpython_context_sensitive.md
index 294f72f968..3c32838f93 100644
--- a/crates/ty_python_semantic/resources/mdtest/basedpython_context_sensitive.md
+++ b/crates/ty_python_semantic/resources/mdtest/basedpython_context_sensitive.md
@@ -321,3 +321,45 @@ def favourite() -> Color:
 enum class Color:
     case Red, Green
 ```
+
+## names that resolve with no binding behind them
+
+this fallback runs at the very *end* of ty's name-resolution chain, so it gates only on the lexical
+scope: anything an earlier entry in that chain resolves has already claimed the name before the enum
+member is ever looked for. that is why it uses the narrower of the two shared name-fallback gates —
+the wider one, which the implicit-receiver and django-lookup rules need, would take these names back
+from the enum for a second time and take one more with them
+
+### an implicit `typing` name keeps its meaning
+
+```by
+enum class Filter:
+    case Any, All
+
+# error: [invalid-assignment] "Object of type `<special-form 'typing.Any'>` is not assignable to `Filter`"
+a: Filter = Any
+```
+
+### `Some` keeps its meaning
+
+```by
+enum class Option:
+    case Some, Nothing
+
+# error: [invalid-assignment] "Object of type `[_SomeT](value: _SomeT, /) -> _SomeT?` is not assignable to `Option`"
+a: Option = Some
+```
+
+### `Character` outside a type expression does not
+
+`Character` is implicitly available only *in* a type expression, so in a value position no earlier
+entry claims it and the enum member answers. this is the one name the two gates observably disagree
+about
+
+```by
+enum class Token:
+    case Character, Digit
+
+a: Token = Character
+reveal_type(a)  # revealed: Token.Character
+```
diff --git a/crates/ty_python_semantic/resources/mdtest/basedpython_implicit_receiver.md b/crates/ty_python_semantic/resources/mdtest/basedpython_implicit_receiver.md
index c8afa0e213..548f1e7049 100644
--- a/crates/ty_python_semantic/resources/mdtest/basedpython_implicit_receiver.md
+++ b/crates/ty_python_semantic/resources/mdtest/basedpython_implicit_receiver.md
@@ -227,6 +227,28 @@ def receiver_of_protocol(fn: protocol(a: int).() -> None) -> None:
     reveal_type(fn)  # revealed: (protocol(a: int), /) -> None
 ```
 
+## names that resolve with no binding behind them
+
+the transpiler asks this rule about a raw name, with none of ty's name-resolution chain behind it,
+so the gate is the *wider* of the two shared name-fallback gates: it claims every name ty resolves
+without a binding, not just the ones the lexical chain owns. `Character` is the witness — implicitly
+available only *in* a type expression, so nothing else claims it in a value position, and the block
+must still not capture it as a receiver member
+
+### a receiver member named `Character` is not captured
+
+```by
+class Lexer:
+    Character: int = 1
+    digit: str = "0"
+
+def apply(fn: Lexer.() -> None) -> None: ...
+
+apply:
+    reveal_type(digit)  # revealed: str
+    Character  # error: [unresolved-reference]
+```
+
 ## `.py` files reject the syntax
 
 ```py
diff --git a/crates/ty_python_semantic/resources/mdtest/external/django.md b/crates/ty_python_semantic/resources/mdtest/external/django.md
index 3206c75bdc..ec3a20d5c6 100644
--- a/crates/ty_python_semantic/resources/mdtest/external/django.md
+++ b/crates/ty_python_semantic/resources/mdtest/external/django.md
@@ -609,3 +609,367 @@ reveal_type(settings.DEBUG)  # revealed: bool
 reveal_type(settings.ROOT_URLCONF)  # revealed: str
 reveal_type(settings.SECRET_KEY)  # revealed: str
 ```
+
+## Model fields in a `.by` file
+
+A constructor call infers as `final CharField[…]` in basedpython, so everything a model's fields
+drive has to read through the use-site modifier to see the class the call constructs.
+
+```by
+from django.db import models
+
+class Author(models.Model):
+    name = models.CharField(max_length=100)
+
+author = Author.objects.get(pk=1)
+reveal_type(author.name)  # revealed: str
+Author.objects.filter(name="x")
+
+# error: [invalid-field-lookup] "Model `Author` has no field `nam`"
+Author.objects.filter(nam="x")
+```
+
+## Lookups written as expressions
+
+basedpython spells the `__` lookup DSL as ordinary expressions. A name in the leading position of a
+comparison that resolves nowhere in the lexical chain, and names a field of the model the queryset
+is over, is a field path — `author.name` traverses the relation exactly as `author__name` does.
+
+```by
+from datetime import date
+from django.db import models
+
+class Author(models.Model):
+    name = models.CharField(max_length=100)
+    age = models.IntegerField()
+
+class Book(models.Model):
+    title = models.CharField(max_length=100)
+    published = models.DateField()
+    author = models.ForeignKey(Author, on_delete=models.CASCADE)
+
+reveal_type(Book.objects.filter(title == "x"))  # revealed: QuerySet[Book, Book]
+Book.objects.filter(published > date(1970, 1, 1))
+Book.objects.filter(published >= date(1970, 1, 1))
+Book.objects.filter(published < date(1970, 1, 1))
+Book.objects.filter(published <= date(1970, 1, 1))
+Book.objects.filter(title in ["a", "b"])
+Book.objects.filter(author.name == "x")
+Book.objects.filter(author.age > 3)
+Book.objects.filter(pk == 1)
+Book.objects.exclude(title == "x")
+Book.objects.get(pk == 1)
+```
+
+## A lookup path types as the fields it names
+
+The leading name is the field, and a relation traverses into the model it targets, so the segments
+after it are ordinary member accesses — including the ones django reads as transforms.
+
+```by
+from django.db import models
+
+class Author(models.Model):
+    name = models.CharField(max_length=100)
+
+class Book(models.Model):
+    title = models.CharField(max_length=100)
+    published = models.DateField()
+    author = models.ForeignKey(Author, on_delete=models.CASCADE)
+
+Book.objects.filter(author.name == "x")
+Book.objects.filter(published.year == 1970)
+
+# a segment after a concrete field is a lookup or a transform, and an unrecognized one is left
+# alone rather than reported — exactly as `filter(published__nonmember=1970)` is today, since
+# django lets a project register lookups of its own
+Book.objects.filter(published.nonmember == 1970)
+```
+
+## An unknown segment is reported
+
+```by
+from django.db import models
+
+class Author(models.Model):
+    name = models.CharField(max_length=100)
+
+class Book(models.Model):
+    title = models.CharField(max_length=100)
+    author = models.ForeignKey(Author, on_delete=models.CASCADE)
+
+# error: [invalid-field-lookup] "Model `Author` has no field `nonfield` (in lookup `author__nonfield`)"
+Book.objects.filter(author.nonfield == "x")
+```
+
+## A value the field cannot hold is reported
+
+```by
+from django.db import models
+
+class Author(models.Model):
+    age = models.IntegerField()
+
+# error: [invalid-field-lookup] "Value for `age__gt` has type `b"x"`, but `Author` expects `int | float | str | Combinable | None`"
+Author.objects.filter(age > b"x")
+```
+
+## Lexical scope wins
+
+A name bound anywhere in the chain keeps its ordinary meaning, so nothing that resolves today
+changes: the comparison is an ordinary `bool` the queryset method takes positionally.
+
+```by
+from django.db import models
+
+class Author(models.Model):
+    name = models.CharField(max_length=100)
+
+def search(name: str) -> None:
+    # `name` is the parameter, not the field
+    reveal_type(Author.objects.filter(name == "x"))  # revealed: QuerySet[Author, Author]
+```
+
+## A builtin is a lexical binding too
+
+`id` names the builtin, so it is never read as the model's primary key. `pk` is the spelling that
+resolves.
+
+```by
+from django.db import models
+
+class Author(models.Model):
+    name = models.CharField(max_length=100)
+
+# no lookup here — `id` is the builtin function
+Author.objects.filter(id == 1)
+Author.objects.filter(pk == 1)
+```
+
+## Operators with no lookup spelling
+
+`!=` has no `__` form — django writes it as `.exclude(...)` or `~Q(...)`, both of which change the
+method being called — so it stays an ordinary comparison and its name stays unresolved.
+
+```by
+from django.db import models
+
+class Author(models.Model):
+    name = models.CharField(max_length=100)
+
+# error: [unresolved-reference] "Name `name` used when not defined"
+Author.objects.filter(name != "x")
+```
+
+## Ordinary arguments pass through
+
+```by
+from django.db import models
+from django.db.models import Q
+
+class Author(models.Model):
+    name = models.CharField(max_length=100)
+    age = models.IntegerField()
+
+def build(kwargs: dict[str, str], q: Q) -> None:
+    Author.objects.filter(Q(name="a") | Q(name="b"))
+    Author.objects.filter(q)
+    Author.objects.filter(**kwargs)
+    Author.objects.filter(name__startswith="x")
+    Author.objects.filter(q, age > 3)
+```
+
+## A json key is a subscript
+
+A `JSONField` holds arbitrary json, so its `__` segments are object keys rather than a closed set of
+lookups. A subscript spells one: `data["key"]` is `data__key`, and what it reads back is json.
+
+```by
+from django.db import models
+
+class Doc(models.Model):
+    data = models.JSONField()
+
+Doc.objects.filter(data["key"] == 1)
+Doc.objects.filter(data["key"] == "x")
+reveal_type(Doc.objects.filter(data["key"] == 1))  # revealed: QuerySet[Doc, Doc]
+```
+
+## Json keys nest, and the operators still apply
+
+```by
+from django.db import models
+
+class Doc(models.Model):
+    data = models.JSONField()
+
+# data__a__b=1
+Doc.objects.filter(data["a"]["b"] == 1)
+# data__key__gt=1
+Doc.objects.filter(data["key"] > 1)
+Doc.objects.filter(data["key"] >= 1)
+Doc.objects.filter(data["key"] < 1)
+Doc.objects.filter(data["key"] <= 1)
+Doc.objects.filter(data["key"] in [1, 2])
+```
+
+## An integer subscript is a json array index
+
+```by
+from django.db import models
+
+class Doc(models.Model):
+    data = models.JSONField()
+
+# data__0=1
+Doc.objects.filter(data[0] == 1)
+# data__0__1=1
+Doc.objects.filter(data[0][1] == 1)
+# data__a__0__gt=1
+Doc.objects.filter(data["a"][0] > 1)
+```
+
+## A json key on a relation's field
+
+```by
+from django.db import models
+
+class Author(models.Model):
+    data = models.JSONField()
+
+class Book(models.Model):
+    author = models.ForeignKey(Author, on_delete=models.CASCADE)
+
+# author__data__key=1
+Book.objects.filter(author.data["key"] == 1)
+```
+
+## An arbitrary json key is not an unknown field
+
+Every string is a legal key, so nothing is reported for one — exactly as nothing is reported for the
+keyword form's `filter(data__anything=1)`.
+
+```by
+from django.db import models
+
+class Doc(models.Model):
+    data = models.JSONField()
+
+Doc.objects.filter(data["not_a_field"] == 1)
+Doc.objects.filter(data__not_a_field=1)
+```
+
+## A subscript on a field with no key transform is left alone
+
+`data["k"]` on a `CharField` is nonsense — django raises `FieldError` for `title__k`. The argument
+keeps the meaning it has today, which leaves its leading name unresolved.
+
+```by
+from django.db import models
+
+class Book(models.Model):
+    title = models.CharField(max_length=100)
+
+# error: [unresolved-reference] "Name `title` used when not defined"
+Book.objects.filter(title["k"] == 1)
+```
+
+## A subscript on a relation is left alone
+
+```by
+from django.db import models
+
+class Author(models.Model):
+    name = models.CharField(max_length=100)
+
+class Book(models.Model):
+    author = models.ForeignKey(Author, on_delete=models.CASCADE)
+
+# error: [unresolved-reference] "Name `author` used when not defined"
+Book.objects.filter(author["k"] == 1)
+```
+
+## A json key django reads as a lookup is left alone
+
+Django resolves the last segment of a keyword as a lookup when the field has one by that name, so
+`data__gt=1` asks for `data > 1` rather than for the key `"gt"`. There is no keyword that spells
+that key, so the subscript is refused rather than lowered to a different query.
+
+```by
+from django.db import models
+
+class Doc(models.Model):
+    data = models.JSONField()
+
+# error: [unresolved-reference] "Name `data` used when not defined"
+Doc.objects.filter(data["gt"] == 1)
+```
+
+## A json key with no keyword spelling is left alone
+
+Django reads a segment that parses as an integer as an array index, so the string key `"0"` has no
+`__` form of its own. Nor does a key that is not spellable inside an identifier, one holding the
+`__` separator, or a negative index.
+
+```by
+from django.db import models
+
+class Doc(models.Model):
+    data = models.JSONField()
+
+def refusals() -> None:
+    # error: [unresolved-reference] "Name `data` used when not defined"
+    Doc.objects.filter(data["0"] == 1)
+    # error: [unresolved-reference] "Name `data` used when not defined"
+    Doc.objects.filter(data["a b"] == 1)
+    # error: [unresolved-reference] "Name `data` used when not defined"
+    Doc.objects.filter(data["a__b"] == 1)
+    # error: [unresolved-reference] "Name `data` used when not defined"
+    Doc.objects.filter(data[-1] == 1)
+```
+
+## A subscript that is not a literal is left alone
+
+A key held in a variable cannot be read here, and a slice is `ArrayField`'s spelling, which a json
+field reads as an index.
+
+```by
+from django.db import models
+
+class Doc(models.Model):
+    data = models.JSONField()
+
+def refusals(key: str) -> None:
+    # error: [unresolved-reference] "Name `data` used when not defined"
+    Doc.objects.filter(data[key] == 1)
+    # error: [unresolved-reference] "Name `data` used when not defined"
+    Doc.objects.filter(data[1:2] == 1)
+```
+
+## A dot after a json key is left alone
+
+The dotted part of a path names the field; a dot after a subscript names nothing django spells.
+
+```by
+from django.db import models
+
+class Doc(models.Model):
+    data = models.JSONField()
+
+# error: [unresolved-reference] "Name `data` used when not defined"
+Doc.objects.filter(data["a"].b == 1)
+```
+
+## A path segment django would read back as two is left alone
+
+Nothing escapes the `__` separator, so a dunder attribute spells more segments than the path has.
+
+```by
+from django.db import models
+
+class Book(models.Model):
+    published = models.DateField()
+
+# error: [unresolved-reference] "Name `published` used when not defined"
+Book.objects.filter(published.__class__ == 1)
+```
diff --git a/crates/ty_python_semantic/src/lib.rs b/crates/ty_python_semantic/src/lib.rs
index 4fb675aa6f..20a355c926 100644
--- a/crates/ty_python_semantic/src/lib.rs
+++ b/crates/ty_python_semantic/src/lib.rs
@@ -20,8 +20,9 @@ use ruff_db::parsed::parsed_module;
 use ruff_db::source::{SourceTextError, source_text};
 use rustc_hash::FxHasher;
 pub use semantic_model::{
-    Completion, ExpectedStringLiteralCompletion, HasDefinition, HasOptionalDefinition, HasType,
-    ImplicitReceiverReference, MemberDefinition, NameKind, SemanticModel,
+    Completion, DjangoLookupArgument, ExpectedStringLiteralCompletion, HasDefinition,
+    HasOptionalDefinition, HasType, ImplicitReceiverReference, MemberDefinition, NameKind,
+    SemanticModel,
 };
 use std::hash::BuildHasherDefault;
 pub use suppression::{
diff --git a/crates/ty_python_semantic/src/semantic_model.rs b/crates/ty_python_semantic/src/semantic_model.rs
index 8eb1229f34..0b77a52225 100644
--- a/crates/ty_python_semantic/src/semantic_model.rs
+++ b/crates/ty_python_semantic/src/semantic_model.rs
@@ -7,7 +7,7 @@ use ruff_python_ast::{self as ast, ExprStringLiteral, ModExpression};
 use ruff_python_ast::{Expr, ExprRef, name::Name};
 use ruff_python_parser::Parsed;
 use ruff_source_file::LineIndex;
-use ruff_text_size::Ranged;
+use ruff_text_size::{Ranged, TextRange};
 use rustc_hash::{FxHashMap, FxHashSet};
 use ty_module_resolver::{
     KnownModule, Module, ModuleName, list_modules, resolve_module, resolve_real_shadowable_module,
@@ -441,6 +441,35 @@ impl<'db> SemanticModel<'db> {
         })
     }
 
+    /// basedpython: how each positional argument of a django lookup method that
+    /// spells a `__` lookup as an expression lowers to a keyword —
+    /// `filter(author.name == "x")` → `filter(author__name="x")`. Empty for
+    /// every other call, and for any argument the checker did not read as a
+    /// lookup, which the transpiler must then leave exactly as written
+    pub fn django_lookup_arguments(&self, call: &ast::ExprCall) -> Vec<DjangoLookupArgument> {
+        let db = self.db;
+        let Some(callee) = call.func.inferred_type(self) else {
+            return Vec::new();
+        };
+        let Some(scope) = self.scope(ast::AnyNodeRef::from(call)) else {
+            return Vec::new();
+        };
+        crate::types::dedicated::django::lookup_call_lowering(
+            db,
+            self.file,
+            scope.to_scope_id(db, self.file),
+            callee,
+            call,
+        )
+        .into_iter()
+        .map(|lowering| DjangoLookupArgument {
+            argument: lowering.argument,
+            key: lowering.key,
+            value: lowering.value,
+        })
+        .collect()
+    }
+
     /// basedpython: the enum a *context-sensitively* resolved name must be
     /// qualified with in the emitted python — `Red` in a `Color` context lowers
     /// to `Color.Red`. `None` for every name that resolves the ordinary way
@@ -1141,6 +1170,18 @@ pub struct MemberDefinition<'db> {
     pub first_reachable_definition: Definition<'db>,
 }
 
+/// basedpython: one positional argument of a django lookup method that spells a
+/// `__` lookup as an expression, and the keyword it lowers to
+#[derive(Clone, Debug)]
+pub struct DjangoLookupArgument {
+    /// the argument to replace
+    pub argument: TextRange,
+    /// the keyword's name (`author__name`, `published__gt`)
+    pub key: String,
+    /// the value, re-emitted from source so lowerings inside it still apply
+    pub value: TextRange,
+}
+
 /// basedpython: what a bare name inside a trailing lambda block resolves to
 /// through the block's callback receiver
 #[derive(Clone, Copy, Debug, Eq, PartialEq)]
diff --git a/crates/ty_python_semantic/src/types.rs b/crates/ty_python_semantic/src/types.rs
index f30573370f..c0ab652859 100644
--- a/crates/ty_python_semantic/src/types.rs
+++ b/crates/ty_python_semantic/src/types.rs
@@ -167,7 +167,7 @@ pub mod context_params;
 pub(crate) mod context_sensitive;
 pub(crate) mod conversions;
 mod cyclic;
-mod dedicated;
+pub(crate) mod dedicated;
 mod deferred;
 mod diagnostic;
 pub(crate) mod display;
@@ -193,6 +193,7 @@ pub(crate) mod match_type;
 mod member;
 mod method;
 mod mro;
+pub(crate) mod name_fallback;
 pub(crate) mod narrow;
 pub(crate) mod narrowing_guards;
 mod newtype;
diff --git a/crates/ty_python_semantic/src/types/context_sensitive.rs b/crates/ty_python_semantic/src/types/context_sensitive.rs
index 15a9730a3d..29f48a4a02 100644
--- a/crates/ty_python_semantic/src/types/context_sensitive.rs
+++ b/crates/ty_python_semantic/src/types/context_sensitive.rs
@@ -17,6 +17,11 @@
 //!   name — resolves to nothing rather than picking one
 //! - a name the scope binds *anywhere* is left alone, even where the binding is
 //!   not yet in flow, because the transpiler cannot see flow
+//!
+//! that last rule is [`claimed_by_lexical_scope`], the narrower of the two shared
+//! [name-fallback](crate::types::name_fallback) gates: this rule runs at the very
+//! end of ty's name-resolution chain, so every name resolved without a binding
+//! has already claimed itself before it is reached
 
 use std::ops::ControlFlow;
 
@@ -26,10 +31,11 @@ use ty_python_core::scope::ScopeId;
 use ty_python_core::{place_table, semantic_index};
 
 use crate::Db;
-use crate::place::{ConsideredDefinitions, builtins_symbol, symbol};
+use crate::place::{ConsideredDefinitions, symbol};
 use crate::types::class::{ClassLiteral, ClassType, based_enum_of_variant};
 use crate::types::class_base::ClassBase;
 use crate::types::literal::EnumLiteralType;
+use crate::types::name_fallback::claimed_by_lexical_scope;
 use crate::types::receivers;
 use crate::types::{Type, TypeContext};
 
@@ -96,7 +102,7 @@ pub(crate) fn resolve_in_context<'db>(
     // scope binds at all — so a name the scope binds anywhere keeps its ordinary
     // meaning here too, or `a: Color = Red` followed by `Red = 1` would check
     // clean and `NameError` at runtime
-    if is_bound_anywhere(db, file, scope, name) {
+    if claimed_by_lexical_scope(db, file, scope, name) {
         return None;
     }
     let Search::Found(member) = search(db, target, name) else {
@@ -129,7 +135,7 @@ pub(crate) fn explain_miss<'db>(
     let target = tcx.context_sensitive_target()?;
     match search(db, target, name) {
         Search::Ambiguous(first, second) => Some(Miss::Ambiguous(first, second)),
-        Search::Found(member) if is_bound_anywhere(db, file, scope, name) => {
+        Search::Found(member) if claimed_by_lexical_scope(db, file, scope, name) => {
             Some(Miss::Shadowed(member.enum_class))
         }
         Search::Found(member) if !is_nameable(db, file, scope, member.enum_class) => {
@@ -256,7 +262,7 @@ pub(crate) fn qualifier_for_unbound_name<'db>(
     // a builtin, keeps its ordinary spelling. checked before the name's type is
     // asked for, so a file that uses no context-sensitive name is never inferred
     // on its account
-    if is_bound_anywhere(db, file, scope, name) {
+    if claimed_by_lexical_scope(db, file, scope, name) {
         return None;
     }
     // a trailing lambda block's receiver member answers *before* this fallback
@@ -298,23 +304,3 @@ fn declares_member<'db>(db: &'db dyn Db, enum_class: ClassLiteral<'db>, name: &s
         .ignore_possibly_undefined()
         .is_some_and(|ty| is_variant_class(db, ty))
 }
-
-/// whether the name is one an ordinary lookup owns — bound or declared somewhere
-/// in the lexical chain, or a builtin
-///
-/// this is the predicate *both* halves gate on, and it is deliberately coarser
-/// than the flow-sensitive lookup that reaches the fallback: the transpiler has
-/// no flow information, so a scope that binds the name anywhere takes it back
-/// from context-sensitive resolution everywhere
-fn is_bound_anywhere<'db>(db: &'db dyn Db, file: File, scope: ScopeId<'db>, name: &str) -> bool {
-    let index = semantic_index(db, file);
-    for (ancestor_id, _) in index.visible_ancestor_scopes(scope.file_scope_id(db)) {
-        let ancestor_scope = ancestor_id.to_scope_id(db, file);
-        if let Some(place) = place_table(db, ancestor_scope).symbol_by_name(name)
-            && (place.is_bound() || place.is_declared())
-        {
-            return true;
-        }
-    }
-    !builtins_symbol(db, name).place.is_undefined()
-}
diff --git a/crates/ty_python_semantic/src/types/dedicated/django.rs b/crates/ty_python_semantic/src/types/dedicated/django.rs
index 7b7e808957..09a9a46e03 100644
--- a/crates/ty_python_semantic/src/types/dedicated/django.rs
+++ b/crates/ty_python_semantic/src/types/dedicated/django.rs
@@ -15,9 +15,10 @@ use ruff_db::files::File;
 use ruff_db::parsed::ParsedModuleRef;
 use ruff_python_ast as ast;
 use ruff_python_ast::name::Name;
-use ruff_text_size::TextRange;
+use ruff_text_size::{Ranged, TextRange};
 use ty_module_resolver::{KnownModule, file_to_module};
 use ty_python_core::definition::{Definition, DefinitionKind, DefinitionState};
+use ty_python_core::scope::ScopeId;
 use ty_python_core::{global_scope, place_table, use_def_map};
 
 use crate::place::{Place, known_module_symbol};
@@ -25,6 +26,7 @@ use crate::types::class::{CodeGeneratorKind, Field, FieldKind};
 use crate::types::function::FunctionType;
 use crate::types::list_members::all_end_of_scope_members;
 use crate::types::member::class_member;
+use crate::types::name_fallback::claimed_by_name_resolution;
 use crate::types::signatures::{Parameter, Parameters, Signature};
 use crate::types::{
     ClassBase, ClassLiteral, ClassType, KnownClass, StaticClassLiteral, Type, UnionType,
@@ -290,8 +292,27 @@ pub(in crate::types) fn is_many_to_many_instance(db: &dyn Db, ty: Type<'_>) -> b
         .is_some_and(|class| has_base(db, class, KnownClass::DjangoManyToManyField))
 }
 
+/// `ty` is an instance of `JSONField` — the one built-in field whose `__`
+/// segments are arbitrary object keys and array indices rather than a closed set
+/// of lookups
+fn is_json_field_instance(db: &dyn Db, ty: Type<'_>) -> bool {
+    instance_static_class(db, ty)
+        .is_some_and(|class| has_base_named(db, class, "django.db.models.fields.json", "JSONField"))
+}
+
+/// the nominal class of an instance type, with a basedpython use-site modifier
+/// erased first
+///
+/// every question in this module is about the class a value is an instance of,
+/// and a constructor call in a `.by` file infers as `final CharField[…]` — a
+/// restricted type, whose nominal class is nothing at all. reading through the
+/// modifier is what keeps a model's fields visible there
+fn nominal_class<'db>(db: &'db dyn Db, ty: Type<'db>) -> Option<ClassType<'db>> {
+    ty.erase_restriction(db).nominal_class(db)
+}
+
 fn instance_static_class<'db>(db: &'db dyn Db, ty: Type<'db>) -> Option<StaticClassLiteral<'db>> {
-    ty.nominal_class(db)?.class_literal(db).as_static()
+    nominal_class(db, ty)?.class_literal(db).as_static()
 }
 
 /// the per-field facts read from a field constructor call in a class-body
@@ -360,7 +381,7 @@ pub(in crate::types) fn is_abstract_model<'db>(
 
 /// the `_GT` (instance read) side of a pinned field instance type
 fn field_get_type<'db>(db: &'db dyn Db, field_ty: Type<'db>) -> Option<Type<'db>> {
-    let ClassType::Generic(alias) = field_ty.nominal_class(db)? else {
+    let ClassType::Generic(alias) = nominal_class(db, field_ty)? else {
         return None;
     };
     let [_, get_ty] = alias.specialization(db).types(db) else {
@@ -372,7 +393,7 @@ fn field_get_type<'db>(db: &'db dyn Db, field_ty: Type<'db>) -> Option<Type<'db>
 /// the `_ST` (assignment/lookup) side of a pinned field instance type — the
 /// type django accepts when writing the field or filtering on it exactly
 fn field_set_type<'db>(db: &'db dyn Db, field_ty: Type<'db>) -> Option<Type<'db>> {
-    let ClassType::Generic(alias) = field_ty.nominal_class(db)? else {
+    let ClassType::Generic(alias) = nominal_class(db, field_ty)? else {
         return None;
     };
     let [set_ty, _] = alias.specialization(db).types(db) else {
@@ -592,7 +613,7 @@ fn m2m_target_and_through<'db>(
     db: &'db dyn Db,
     field_ty: Type<'db>,
 ) -> Option<(Type<'db>, Type<'db>)> {
-    let ClassType::Generic(alias) = field_ty.nominal_class(db)? else {
+    let ClassType::Generic(alias) = nominal_class(db, field_ty)? else {
         return None;
     };
     let [target, through] = alias.specialization(db).types(db) else {
@@ -726,7 +747,7 @@ pub(in crate::types) fn queryset_or_manager_model<'db>(
     db: &'db dyn Db,
     self_instance: Type<'db>,
 ) -> Option<StaticClassLiteral<'db>> {
-    let class = self_instance.nominal_class(db)?;
+    let class = nominal_class(db, self_instance)?;
     let is_qs_or_manager = class.class_literal(db).as_static().is_some_and(|literal| {
         has_base(db, literal, KnownClass::DjangoManager)
             || has_base(db, literal, KnownClass::DjangoQuerySet)
@@ -795,6 +816,10 @@ struct FieldRef<'db> {
     /// the type read back from a `values()`/`values_list()` row — the field's
     /// `_GT` for a concrete field, the target pk for a bare relation
     value_type: Type<'db>,
+    /// the field descriptor's own declared type (`CharField[str, str]`), for the
+    /// questions only the field *class* answers. `None` for a name the model
+    /// declares no field for — `pk`, and the synthesized `<fk>_id` attnames
+    declared_type: Option<Type<'db>>,
 }
 
 /// resolve `name` (a real field, `pk`, `id`, or an `<fk>_id` attname) on
@@ -813,6 +838,7 @@ fn field_ref<'db>(
             is_relation: false,
             set_type: pk,
             value_type: pk,
+            declared_type: None,
         });
     }
 
@@ -832,6 +858,7 @@ fn field_ref<'db>(
                 is_relation: true,
                 set_type: Type::unknown(),
                 value_type,
+                declared_type: Some(field.declared_ty),
             });
         }
         return Some(FieldRef {
@@ -839,6 +866,7 @@ fn field_ref<'db>(
             is_relation: false,
             set_type: field_set_type(db, field.declared_ty).unwrap_or_else(Type::unknown),
             value_type: field_get_type(db, field.declared_ty).unwrap_or_else(Type::unknown),
+            declared_type: Some(field.declared_ty),
         });
     }
 
@@ -849,6 +877,7 @@ fn field_ref<'db>(
             is_relation: false,
             set_type: synthesized,
             value_type: synthesized,
+            declared_type: None,
         });
     }
 
@@ -953,6 +982,392 @@ pub(in crate::types) fn resolve_lookup<'db>(
     }
 }
 
+// ---------------------------------------------------------------------------
+// lookup expressions
+//
+// basedpython writes django's `__` lookup DSL as ordinary expressions:
+// `filter(author.name == "x")` for `filter(author__name="x")`. the names in such
+// an expression are field paths rather than values, so what counts as one is
+// decided here, once — the checker types the path from this answer and the
+// transpiler lowers it from the same one, so the two can't disagree about which
+// query a call describes
+// ---------------------------------------------------------------------------
+
+/// the `__` lookup suffix a comparison operator spells, empty for the implicit
+/// `exact`
+///
+/// `!=` is deliberately absent: django spells it as `.exclude(a=1)` or `~Q(a=1)`,
+/// both of which change the queryset method being called, and a lowering that
+/// silently swapped `filter` for `exclude` would rewrite the query rather than
+/// spell it
+fn lookup_suffix(op: ast::CmpOp) -> Option<&'static str> {
+    match op {
+        ast::CmpOp::Eq => Some(""),
+        ast::CmpOp::Gt => Some("gt"),
+        ast::CmpOp::GtE => Some("gte"),
+        ast::CmpOp::Lt => Some("lt"),
+        ast::CmpOp::LtE => Some("lte"),
+        ast::CmpOp::In => Some("in"),
+        _ => None,
+    }
+}
+
+/// whether `method` accepts a lookup written as a positional expression
+///
+/// only the methods whose stub declares `*args` do. the `*_or_create` family is
+/// a lookup method too, but its first positional parameter is `defaults`, so an
+/// expression there would bind to that rather than to the keywords it lowers to
+pub(crate) fn accepts_lookup_expressions(method: &str) -> bool {
+    matches!(method, "filter" | "exclude" | "get" | "aget")
+}
+
+/// django's lookups on a `JSONField`, which decide when a `__` segment on one is
+/// read as a lookup rather than as an object key
+///
+/// django resolves the *final* segment of a key as a lookup when the field has
+/// one by that name, and as a key otherwise, with nothing reported either way. a
+/// subscript says "key" outright, so a key that collides with one of these has no
+/// `__` spelling at all and is refused — emitting `data__gt=1` for `data["gt"]`
+/// would silently ask for `data > 1` instead
+///
+/// this is the set `JSONField.get_lookups()` answers with, measured against
+/// django 6.0. a project that registers a lookup of its own on `JSONField` widens
+/// it, which is not visible from here
+const JSON_FIELD_LOOKUPS: &[&str] = &[
+    "contained_by",
+    "contains",
+    "endswith",
+    "exact",
+    "gt",
+    "gte",
+    "has_any_keys",
+    "has_key",
+    "has_keys",
+    "icontains",
+    "iendswith",
+    "iexact",
+    "in",
+    "iregex",
+    "isnull",
+    "istartswith",
+    "lt",
+    "lte",
+    "range",
+    "regex",
+    "startswith",
+];
+
+/// one positional argument that spells a field lookup as an expression
+pub(crate) struct LookupExpression<'a, 'db> {
+    /// the whole argument — the comparison the keyword replaces
+    pub(crate) argument: &'a ast::Expr,
+    /// the field path's nodes, root first: a `Name`, then its `Attribute`s and
+    /// `Subscript`s
+    pub(crate) path: Vec<&'a ast::Expr>,
+    /// the type the root name takes — a relation's target model instance, so
+    /// the rest of the path is ordinary member access
+    pub(crate) root_type: Type<'db>,
+    /// the value the field is compared against
+    pub(crate) value: &'a ast::Expr,
+    /// the keyword this lowers to (`author__name`, `published__gt`)
+    pub(crate) key: String,
+}
+
+/// the field path `expr` spells, as its nodes root first. `None` for anything
+/// that is not a plain `a.b["c"]` of loads — a call, an optional-chain link, an
+/// arithmetic operand
+fn field_path(expr: &ast::Expr) -> Option<Vec<&ast::Expr>> {
+    let mut path = Vec::new();
+    let mut current = expr;
+    loop {
+        match current {
+            ast::Expr::Name(name) if name.ctx.is_load() => {
+                path.push(current);
+                path.reverse();
+                return Some(path);
+            }
+            ast::Expr::Attribute(attribute) if attribute.ctx.is_load() && !attribute.optional => {
+                path.push(current);
+                current = &attribute.value;
+            }
+            // `typeof X` wears a subscript's shape without being one
+            ast::Expr::Subscript(subscript) if subscript.ctx.is_load() && !subscript.is_typeof => {
+                path.push(current);
+                current = &subscript.value;
+            }
+            _ => return None,
+        }
+    }
+}
+
+/// the `__` segment a subscript spells on a json field: an object key or an array
+/// index. `None` for every subscript django's transforms cannot spell
+///
+/// django builds its json path by trying `int()` on each segment, so a segment
+/// that reads as an integer is an *index* and anything else is a key. that leaves
+/// the string `"0"` with no spelling of its own — `data__0` is the index — and a
+/// negative index with none either, since `data__-1` is not a keyword name
+fn subscript_segment(subscript: &ast::ExprSubscript) -> Option<Cow<'_, str>> {
+    match &*subscript.slice {
+        ast::Expr::NumberLiteral(number) => {
+            let ast::Number::Int(index) = &number.value else {
+                return None;
+            };
+            Some(Cow::Owned(index.as_u64()?.to_string()))
+        }
+        ast::Expr::StringLiteral(literal) => {
+            let key = literal.value.to_str();
+            // the key rides in a keyword's name, so it has to be spellable as
+            // one. this also settles the numeric keys: no identifier reads as an
+            // integer, so `data["0"]` is refused while `data[0]` is the index
+            if !ruff_python_stdlib::identifiers::is_identifier(key) {
+                return None;
+            }
+            if JSON_FIELD_LOOKUPS.contains(&key) {
+                return None;
+            }
+            Some(Cow::Borrowed(key))
+        }
+        // a variable key can't be read here, and a slice is postgres' `ArrayField`
+        // spelling, which reads as an index on a json field
+        _ => None,
+    }
+}
+
+/// the `__` key `segments` spell, or `None` when django would read the joined
+/// text back as a different list than the one that went in
+///
+/// django splits a keyword on `__` and nothing escapes it, so a segment holding
+/// `__` (a json key), one ending in `_` ahead of another (`data["a_"] > 1`) and a
+/// dunder attribute all mean something other than the path they came from
+fn assemble_key(segments: &[Cow<'_, str>]) -> Option<String> {
+    let key = segments.join("__");
+    key.split("__")
+        .eq(segments.iter().map(Cow::as_ref))
+        .then_some(key)
+}
+
+/// the field the plain-name segments `names` reach from `model`, traversing
+/// relations. `None` unless every leading segment is a relation and the last is a
+/// field the model declares
+fn path_field<'db>(
+    db: &'db dyn Db,
+    model: StaticClassLiteral<'db>,
+    names: &[&str],
+) -> Option<FieldRef<'db>> {
+    let (&last, leading) = names.split_last()?;
+    let mut model = model;
+    for name in leading {
+        let field = field_ref(db, model, name)?;
+        if !field.is_relation {
+            return None;
+        }
+        model = field.relation_model?;
+    }
+    field_ref(db, model, last)
+}
+
+/// the type the leading name of a lookup path takes: the target model's instance
+/// for a relation, so the segments after it are ordinary member accesses on the
+/// model they traverse into; the field's own read type otherwise
+fn lookup_root_type<'db>(
+    db: &'db dyn Db,
+    model: StaticClassLiteral<'db>,
+    name: &str,
+) -> Option<Type<'db>> {
+    // a many-to-many field's `_GT` is its *through* model, not its target
+    if let Some(field) = model.fields(db, None, CodeGeneratorKind::Django).get(name)
+        && is_many_to_many_instance(db, field.declared_ty)
+    {
+        return m2m_target_and_through(db, field.declared_ty).map(|(target, _)| target);
+    }
+    let field = field_ref(db, model, name)?;
+    if field.is_relation {
+        // an unresolved relation target leaves nothing to traverse into
+        let target = field.relation_model?;
+        return Some(Type::instance(db, target.default_specialization(db)));
+    }
+    Some(field.value_type)
+}
+
+/// the positional arguments of a lookup-method call that spell a lookup as an
+/// expression, in source order
+///
+/// every gate here is a refusal: an argument this declines to classify keeps the
+/// meaning it has today, and the transpiler leaves it exactly as written
+pub(crate) fn lookup_expressions<'a, 'db>(
+    db: &'db dyn Db,
+    file: File,
+    scope: ScopeId<'db>,
+    model: StaticClassLiteral<'db>,
+    arguments: &'a ast::Arguments,
+) -> Vec<LookupExpression<'a, 'db>> {
+    let mut classified: Vec<Option<LookupExpression<'a, 'db>>> = arguments
+        .args
+        .iter()
+        .map(|argument| lookup_expression(db, file, scope, model, argument))
+        .collect();
+
+    // a lookup lowers to a keyword argument, which python requires after every
+    // positional one, so only the trailing run of classified arguments can be
+    // lowered — one followed by an argument that stays positional keeps its own
+    // meaning too
+    let trailing_run = classified
+        .iter()
+        .rposition(Option::is_none)
+        .map_or(0, |last| last + 1);
+    classified.drain(..trailing_run);
+
+    // a key written twice is a duplicate keyword argument, which is a syntax
+    // error rather than a query; a key an explicit keyword already spells is the
+    // same collision
+    let mut seen: Vec<&str> = arguments
+        .keywords
+        .iter()
+        .filter_map(|keyword| keyword.arg.as_ref())
+        .map(ast::Identifier::as_str)
+        .collect();
+    let mut duplicated = Vec::new();
+    for lookup in classified.iter().flatten() {
+        if seen.contains(&lookup.key.as_str()) {
+            duplicated.push(lookup.key.clone());
+        }
+        seen.push(&lookup.key);
+    }
+
+    classified
+        .into_iter()
+        .flatten()
+        .filter(|lookup| !duplicated.contains(&lookup.key))
+        .collect()
+}
+
+/// the model a call spells lookups against, when its callee is a queryset /
+/// manager method that takes them as positional expressions
+pub(crate) fn lookup_call_model<'db>(
+    db: &'db dyn Db,
+    callee: Type<'db>,
+) -> Option<StaticClassLiteral<'db>> {
+    let Type::BoundMethod(bound_method) = callee else {
+        return None;
+    };
+    let name = bound_method.function(db).name(db);
+    if queryset_method_kind(name.as_str()) != Some(QuerysetMethodKind::Lookup)
+        || !accepts_lookup_expressions(name.as_str())
+    {
+        return None;
+    }
+    queryset_or_manager_model(db, bound_method.self_instance(db))
+}
+
+/// the keyword a lookup expression lowers to, as source ranges — the whole
+/// argument is replaced by `<key>=<value>`
+pub(crate) struct LookupLowering {
+    /// the argument to replace
+    pub(crate) argument: TextRange,
+    /// the keyword's name
+    pub(crate) key: String,
+    /// the value, re-emitted from source so lowerings inside it still apply
+    pub(crate) value: TextRange,
+}
+
+/// how each lookup expression in `call` lowers, when `callee` is a lookup method
+/// on a resolved model
+///
+/// a path that doesn't resolve against the model is left out: the checker
+/// reports it, and lowering it would emit a keyword django itself rejects
+pub(crate) fn lookup_call_lowering<'db>(
+    db: &'db dyn Db,
+    file: File,
+    scope: ScopeId<'db>,
+    callee: Type<'db>,
+    call: &ast::ExprCall,
+) -> Vec<LookupLowering> {
+    let Some(model) = lookup_call_model(db, callee) else {
+        return Vec::new();
+    };
+    lookup_expressions(db, file, scope, model, &call.arguments)
+        .into_iter()
+        .filter(|lookup| {
+            matches!(
+                resolve_lookup(db, model, &lookup.key),
+                FieldResolution::Resolved { .. }
+            )
+        })
+        .map(|lookup| LookupLowering {
+            argument: lookup.argument.range(),
+            key: lookup.key,
+            value: lookup.value.range(),
+        })
+        .collect()
+}
+
+fn lookup_expression<'a, 'db>(
+    db: &'db dyn Db,
+    file: File,
+    scope: ScopeId<'db>,
+    model: StaticClassLiteral<'db>,
+    argument: &'a ast::Expr,
+) -> Option<LookupExpression<'a, 'db>> {
+    let ast::Expr::Compare(compare) = argument else {
+        return None;
+    };
+    // a chained comparison names no single lookup
+    let ([op], [value]) = (&*compare.ops, &*compare.comparators) else {
+        return None;
+    };
+    let suffix = lookup_suffix(*op)?;
+    let path = field_path(&compare.left)?;
+    let root = path.first()?.as_name_expr()?;
+
+    // anything that already claims the name wins, exactly as it does for an
+    // implicit receiver: this is asked of a raw name by the transpiler too, so it
+    // takes the wider of the two name-fallback gates
+    if claimed_by_name_resolution(db, file, scope, root.id.as_str()) {
+        return None;
+    }
+    let root_type = lookup_root_type(db, model, root.id.as_str())?;
+
+    // the dotted part of the path names the field; the subscripts after it index
+    // into it, so a dot *after* a subscript names nothing django can spell
+    let mut names = vec![root.id.as_str()];
+    let mut keys = Vec::new();
+    for node in &path[1..] {
+        match node {
+            ast::Expr::Attribute(attribute) if keys.is_empty() => {
+                names.push(attribute.attr.as_str());
+            }
+            ast::Expr::Subscript(subscript) => keys.push(subscript_segment(subscript)?),
+            _ => return None,
+        }
+    }
+
+    if !keys.is_empty() {
+        // only a json field carries the key and index transforms a subscript
+        // spells. on anything else django rejects the keyword at runtime, so a
+        // subscript there is left as written
+        let field = path_field(db, model, &names)?;
+        if !is_json_field_instance(db, field.declared_type?) {
+            return None;
+        }
+    }
+
+    let mut segments: Vec<Cow<'_, str>> = names.into_iter().map(Cow::Borrowed).collect();
+    segments.extend(keys);
+    if !suffix.is_empty() {
+        segments.push(Cow::Borrowed(suffix));
+    }
+    let key = assemble_key(&segments)?;
+
+    Some(LookupExpression {
+        argument,
+        path,
+        root_type,
+        value,
+        key,
+    })
+}
+
 /// resolve a `create()` keyword: the field's assignable type, or `Unknown`
 /// when the key names no field / attname of the model
 pub(in crate::types) fn resolve_create_kwarg<'db>(
@@ -1257,7 +1672,7 @@ pub(in crate::types) fn with_queryset_row<'db>(
     queryset_ty: Type<'db>,
     row: Type<'db>,
 ) -> Option<Type<'db>> {
-    let ClassType::Generic(alias) = queryset_ty.nominal_class(db)? else {
+    let ClassType::Generic(alias) = nominal_class(db, queryset_ty)? else {
         return None;
     };
     let [model_arg, _] = alias.specialization(db).types(db) else {
@@ -1371,7 +1786,7 @@ fn substitute_model<'db>(
     if declared_return.is_dynamic() {
         return Some(model_instance);
     }
-    let ClassType::Generic(alias) = declared_return.nominal_class(db)? else {
+    let ClassType::Generic(alias) = nominal_class(db, declared_return)? else {
         return None;
     };
     let arity = alias.specialization(db).types(db).len();
@@ -1569,11 +1984,171 @@ fn declared_by_django<'db>(db: &'db dyn Db, class: StaticClassLiteral<'db>, name
 
 #[cfg(test)]
 mod tests {
-    use super::ALTERS_DATA_METHODS;
+    use std::borrow::Cow;
+
+    use ruff_python_ast as ast;
+    use ruff_python_parser::{Mode, ParseOptions, parse};
+
+    use super::{
+        ALTERS_DATA_METHODS, JSON_FIELD_LOOKUPS, assemble_key, field_path, lookup_suffix,
+        subscript_segment,
+    };
 
     #[test]
     fn the_marked_methods_are_sorted() {
         // `refuses_template_call` binary-searches them
         assert!(ALTERS_DATA_METHODS.windows(2).all(|pair| pair[0] < pair[1]));
     }
+
+    #[test]
+    fn only_the_operators_django_spells_map_to_a_suffix() {
+        for (op, expected) in [
+            (ast::CmpOp::Eq, Some("")),
+            (ast::CmpOp::Gt, Some("gt")),
+            (ast::CmpOp::GtE, Some("gte")),
+            (ast::CmpOp::Lt, Some("lt")),
+            (ast::CmpOp::LtE, Some("lte")),
+            (ast::CmpOp::In, Some("in")),
+            (ast::CmpOp::NotEq, None),
+            (ast::CmpOp::NotIn, None),
+            (ast::CmpOp::Is, None),
+            (ast::CmpOp::IsNot, None),
+        ] {
+            assert_eq!(lookup_suffix(op), expected, "for {op:?}");
+        }
+    }
+
+    fn expression_of(source: &str) -> ast::Expr {
+        let options = ParseOptions::from(Mode::Expression).with_basedpython(true);
+        let parsed = parse(source, options).expect("valid expression");
+        parsed
+            .into_syntax()
+            .as_expression()
+            .expect("expression mode parses to an expression")
+            .body
+            .as_ref()
+            .clone()
+    }
+
+    fn path_of(source: &str) -> Option<Vec<String>> {
+        field_path(&expression_of(source)).map(|path| {
+            path.iter()
+                .map(|node| match node {
+                    ast::Expr::Name(name) => name.id.to_string(),
+                    ast::Expr::Attribute(attribute) => attribute.attr.to_string(),
+                    ast::Expr::Subscript(subscript) => subscript_segment(subscript)
+                        .map_or_else(|| "[?]".to_owned(), |segment| format!("[{segment}]")),
+                    _ => unreachable!("a field path is names, attributes and subscripts"),
+                })
+                .collect()
+        })
+    }
+
+    #[test]
+    fn a_field_path_is_a_dotted_name_with_subscripts() {
+        assert_eq!(path_of("author"), Some(vec!["author".to_owned()]));
+        assert_eq!(
+            path_of("author.name"),
+            Some(vec!["author".to_owned(), "name".to_owned()])
+        );
+        assert_eq!(
+            path_of("data[\"k\"]"),
+            Some(vec!["data".to_owned(), "[k]".to_owned()])
+        );
+        assert_eq!(
+            path_of("author.data[\"k\"][0]"),
+            Some(vec![
+                "author".to_owned(),
+                "data".to_owned(),
+                "[k]".to_owned(),
+                "[0]".to_owned(),
+            ])
+        );
+        // anything else is not a path django could spell with `__`
+        for source in ["f()", "a.b()", "a[0]()", "a().b", "(a + b).c", "typeof a"] {
+            assert_eq!(path_of(source), None, "for `{source}`");
+        }
+    }
+
+    fn segment_of(source: &str) -> Option<String> {
+        let expression = expression_of(source);
+        let subscript = expression
+            .as_subscript_expr()
+            .expect("the source is a subscript");
+        subscript_segment(subscript).map(Cow::into_owned)
+    }
+
+    #[test]
+    fn a_subscript_segment_is_a_literal_key_or_a_non_negative_index() {
+        assert_eq!(segment_of("d[\"key\"]").as_deref(), Some("key"));
+        assert_eq!(segment_of("d[\"_key\"]").as_deref(), Some("_key"));
+        assert_eq!(segment_of("d[0]").as_deref(), Some("0"));
+        assert_eq!(segment_of("d[12]").as_deref(), Some("12"));
+
+        for source in [
+            // a key django reads back as an index
+            "d[\"0\"]",
+            "d[\"1_2\"]",
+            // a key that is not spellable as part of a keyword's name
+            "d[\"a b\"]",
+            "d[\"a.b\"]",
+            "d[\"a-b\"]",
+            "d[\"\"]",
+            // `data__-1` is not a keyword name, so a negative index has no form
+            "d[-1]",
+            // django reads a lookup name as the lookup, not as the key
+            "d[\"gt\"]",
+            "d[\"exact\"]",
+            "d[\"contains\"]",
+            // nothing statically readable
+            "d[k]",
+            "d[1:2]",
+            "d[1.5]",
+            "d[True]",
+            "d[f(1)]",
+            "d[\"a\" + \"b\"]",
+        ] {
+            assert_eq!(segment_of(source), None, "for `{source}`");
+        }
+    }
+
+    fn key_of(segments: &[&str]) -> Option<String> {
+        let segments: Vec<Cow<'_, str>> = segments.iter().copied().map(Cow::Borrowed).collect();
+        assemble_key(&segments)
+    }
+
+    #[test]
+    fn a_key_that_does_not_split_back_into_its_segments_is_refused() {
+        assert_eq!(key_of(&["title"]).as_deref(), Some("title"));
+        assert_eq!(key_of(&["author", "name"]).as_deref(), Some("author__name"));
+        assert_eq!(
+            key_of(&["data", "key", "gt"]).as_deref(),
+            Some("data__key__gt")
+        );
+        assert_eq!(key_of(&["data", "_key"]).as_deref(), Some("data___key"));
+
+        // `data__a___gt` reads back as the key `a` and the lookup `_gt`
+        assert_eq!(key_of(&["data", "a_", "gt"]), None);
+        // a segment holding the separator is two segments to django
+        assert_eq!(key_of(&["data", "a__b"]), None);
+        assert_eq!(key_of(&["published", "__class__"]), None);
+    }
+
+    #[test]
+    fn the_json_lookup_names_are_the_ones_django_registers() {
+        // measured with `JSONField.get_lookups()` against django 6.0; the whole
+        // point of the list is to refuse a key it holds, so a stale *extra* entry
+        // is safe and a missing one is not
+        assert_eq!(JSON_FIELD_LOOKUPS.len(), 21);
+        assert!(
+            JSON_FIELD_LOOKUPS.windows(2).all(|pair| pair[0] < pair[1]),
+            "kept sorted so a diff against django's own list reads"
+        );
+        for spelled in ["exact", "gt", "gte", "lt", "lte", "in"] {
+            assert!(
+                JSON_FIELD_LOOKUPS.contains(&spelled),
+                "the operators the dsl spells must all be refused as keys: {spelled}"
+            );
+        }
+    }
 }
diff --git a/crates/ty_python_semantic/src/types/dedicated/mod.rs b/crates/ty_python_semantic/src/types/dedicated/mod.rs
index 7942ed896c..53a094daee 100644
--- a/crates/ty_python_semantic/src/types/dedicated/mod.rs
+++ b/crates/ty_python_semantic/src/types/dedicated/mod.rs
@@ -1,4 +1,4 @@
-pub(super) mod django;
+pub(crate) mod django;
 pub(super) mod pydantic;
 pub(super) mod pytest;
 pub(super) mod role;
diff --git a/crates/ty_python_semantic/src/types/infer/builder.rs b/crates/ty_python_semantic/src/types/infer/builder.rs
index 318ce019a9..44b673c8c4 100644
--- a/crates/ty_python_semantic/src/types/infer/builder.rs
+++ b/crates/ty_python_semantic/src/types/infer/builder.rs
@@ -10253,6 +10253,64 @@ impl<'db, 'ast> TypeInferenceBuilder<'db, 'ast> {
         Some(Type::float_literal(value))
     }
 
+    /// basedpython: infer the positional arguments of a django lookup method
+    /// that spell a `__` lookup as an expression (`filter(author.name == "x")`),
+    /// reporting whether any did.
+    ///
+    /// The names in such an argument are field paths, not values, so they are
+    /// inferred here rather than through the ordinary load path — the leading
+    /// name takes the field's type (a relation's target model instance), and the
+    /// segments after it are ordinary member accesses on it. The comparison
+    /// itself is a `bool`, exactly as the source spells it; whether the value
+    /// suits the field is [`check_django_queryset_call`]'s question, since the
+    /// keyword form asks it there too.
+    ///
+    /// [`check_django_queryset_call`]: Self::check_django_queryset_call
+    fn prepare_django_lookup_expressions(
+        &mut self,
+        callable_type: Type<'db>,
+        arguments: &ast::Arguments,
+    ) -> bool {
+        if !self.is_basedpython_file() {
+            return false;
+        }
+        let db = self.db();
+        let Some(model) = django::lookup_call_model(db, callable_type) else {
+            return false;
+        };
+        let lookups = django::lookup_expressions(db, self.file(), self.scope(), model, arguments);
+        if lookups.is_empty() {
+            return false;
+        }
+        for lookup in lookups {
+            let mut ty = lookup.root_type;
+            for (index, node) in lookup.path.iter().enumerate() {
+                match node {
+                    ast::Expr::Attribute(attribute) if index > 0 => {
+                        ty = ty
+                            .member(db, attribute.attr.as_str())
+                            .place
+                            .ignore_possibly_undefined()
+                            .unwrap_or_else(Type::unknown);
+                    }
+                    ast::Expr::Subscript(subscript) => {
+                        // the key is part of the keyword's name rather than a
+                        // value, but it is still source that wants a type
+                        self.infer_expression(&subscript.slice, TypeContext::default());
+                        // a json key reads back arbitrary json, which is what the
+                        // stubs say the field itself reads back too
+                        ty = Type::any();
+                    }
+                    _ => {}
+                }
+                self.store_expression_type(node, ty);
+            }
+            self.infer_maybe_standalone_expression(lookup.value, TypeContext::default());
+            self.store_expression_type(lookup.argument, KnownClass::Bool.to_instance(db));
+        }
+        true
+    }
+
     /// Validate a django `Manager`/`QuerySet` method call against the bound
     /// model's fields: lookup kwargs (`filter`, `get`, …), `create()` kwargs,
     /// and literal field-name arguments (`order_by`, `only`, …). No-op for any
@@ -10335,6 +10393,44 @@ impl<'db, 'ast> TypeInferenceBuilder<'db, 'ast> {
                         django::FieldResolution::Resolved { operand: None } => {}
                     }
                 }
+
+                // basedpython: the same checks against the lookups the call's
+                // positional arguments spell as expressions
+                if !is_create && self.is_basedpython_file() {
+                    for lookup in django::lookup_expressions(
+                        db,
+                        self.file(),
+                        self.scope(),
+                        model,
+                        &call_expression.arguments,
+                    ) {
+                        let range = lookup.argument.range();
+                        match django::resolve_lookup(db, model, &lookup.key) {
+                            django::FieldResolution::Unknown { model, segment } => {
+                                report_unknown(range, &model, &segment, &lookup.key);
+                            }
+                            django::FieldResolution::Resolved {
+                                operand: Some(operand),
+                            } => {
+                                let operand =
+                                    UnionType::from_two_elements(db, operand, Type::none(db));
+                                let value_ty = self.expression_type(lookup.value);
+                                if !value_ty.is_assignable_to(db, operand)
+                                    && let Some(builder) =
+                                        self.context.report_lint(&INVALID_FIELD_LOOKUP, range)
+                                {
+                                    builder.into_diagnostic(format_args!(
+                                        "Value for `{}` has type `{}`, but `{model_name}` expects `{}`",
+                                        lookup.key,
+                                        value_ty.display(db),
+                                        operand.display(db),
+                                    ));
+                                }
+                            }
+                            django::FieldResolution::Resolved { operand: None } => {}
+                        }
+                    }
+                }
             }
             django::QuerysetMethodKind::FieldNames => {
                 for arg in &call_expression.arguments.args {
@@ -10768,6 +10864,12 @@ impl<'db, 'ast> TypeInferenceBuilder<'db, 'ast> {
             })
             .is_some();
 
+        // basedpython: a django lookup written as an expression names fields
+        // rather than values, so its own inference has to happen before the
+        // arguments are inferred as ordinary expressions
+        let has_django_lookup_expressions =
+            self.prepare_django_lookup_expressions(callable_type, arguments);
+
         // We don't call `Type::try_call`, because we want to perform type inference on the
         // arguments after matching them to parameters, but before checking that the argument types
         // are assignable to any parameter annotations.
@@ -11107,7 +11209,7 @@ impl<'db, 'ast> TypeInferenceBuilder<'db, 'ast> {
                     Some(groups) => tcx.map(|ty| regex::attach_groups(builder.db(), ty, groups)),
                     None => tcx,
                 };
-                if has_prepared_typed_dict_constructor {
+                if has_prepared_typed_dict_constructor || has_django_lookup_expressions {
                     builder.get_or_infer_expression(expr, tcx)
                 } else {
                     builder.infer_expression(expr, tcx)
diff --git a/crates/ty_python_semantic/src/types/name_fallback.rs b/crates/ty_python_semantic/src/types/name_fallback.rs
new file mode 100644
index 0000000000..473354d0cc
--- /dev/null
+++ b/crates/ty_python_semantic/src/types/name_fallback.rs
@@ -0,0 +1,143 @@
+//! the shared gate for "does anything already claim this name"
+//!
+//! three basedpython rules give an otherwise-unresolvable bare name a meaning,
+//! each as the *last* fallback so nothing that resolves today changes meaning:
+//!
+//! - [context-sensitive resolution](crate::types::context_sensitive): an enum
+//!   member unqualified where the expected type is known (`a: Color = Red`)
+//! - [implicit receivers](crate::types::receivers): a trailing lambda block
+//!   seeing its receiver's members unqualified
+//! - [django lookup expressions](crate::types::dedicated::django): the root of
+//!   `filter(author.name == "x")`
+//!
+//! all three ask the same question of the lexical scope chain, and this module
+//! owns the one walk that answers it. two of them need a *wider* answer, and the
+//! difference is load-bearing rather than accidental: it is whether the caller
+//! sits downstream of ty's own name-resolution fallback chain.
+//!
+//! context-sensitive resolution is reached only from the very end of that chain,
+//! so every name ty resolves without a binding — a basedpython implicit `typing`
+//! name, `Character`, `Some` — has already claimed itself before the enum
+//! fallback runs, and [`claimed_by_lexical_scope`] is enough. the receiver and
+//! django rules are additionally asked *by the transpiler*, about a raw name with
+//! no chain behind it, so they have to replicate those entries themselves:
+//! [`claimed_by_name_resolution`].
+//!
+//! the two are not interchangeable. `Character` outside a type expression is the
+//! witness: no earlier fallback claims it, so an enum member of that name
+//! resolves context-sensitively today, and widening the enum gate to
+//! [`claimed_by_name_resolution`] would silently take that away
+
+use ruff_db::files::File;
+use ty_python_core::scope::ScopeId;
+use ty_python_core::{place_table, semantic_index};
+
+use crate::Db;
+use crate::place::{
+    builtins_symbol, is_basedpython_implicit_typing_name, module_type_implicit_global_symbol,
+};
+
+/// whether an ordinary lexical lookup owns `name`: a binding or a declaration
+/// anywhere in the visible scope chain, or a builtin
+///
+/// deliberately coarser than the flow-sensitive lookup that reaches the
+/// fallbacks. the transpiler has no flow information — it qualifies a name that
+/// no scope binds at all — so a scope that binds the name *anywhere* takes it
+/// back everywhere, or `a: Color = Red` followed by `Red = 1` would check clean
+/// and `NameError` at runtime.
+///
+/// the walk follows python's own rules (a class scope is not visible from a
+/// nested scope), matching the free-variable walk of a name load
+pub(crate) fn claimed_by_lexical_scope(
+    db: &dyn Db,
+    file: File,
+    scope: ScopeId<'_>,
+    name: &str,
+) -> bool {
+    let index = semantic_index(db, file);
+    for (ancestor_id, _) in index.visible_ancestor_scopes(scope.file_scope_id(db)) {
+        let ancestor_scope = ancestor_id.to_scope_id(db, file);
+        if place_table(db, ancestor_scope)
+            .symbol_by_name(name)
+            .is_some_and(|symbol| symbol.is_bound() || symbol.is_declared())
+        {
+            return true;
+        }
+    }
+    !builtins_symbol(db, name).place.is_undefined()
+}
+
+/// [`claimed_by_lexical_scope`], and additionally every name ty resolves with no
+/// binding behind it: an implicit module global, a basedpython implicit `typing`
+/// name, and the two implicit names that have no stub to resolve through.
+///
+/// for the callers the name-resolution fallback chain has *not* already run for,
+/// so it errs towards "yes": a name this missed would resolve as something else
+/// while the transpiler — which re-derives the rewrite from this same answer —
+/// lowered it as a receiver member or a lookup path
+pub(crate) fn claimed_by_name_resolution(
+    db: &dyn Db,
+    file: File,
+    scope: ScopeId<'_>,
+    name: &str,
+) -> bool {
+    claimed_by_lexical_scope(db, file, scope, name)
+        // states the intent directly rather than leaning on the fact that the
+        // builtins lookup above happens to fall back to `types.ModuleType` too
+        || !module_type_implicit_global_symbol(db, file, name)
+            .place
+            .is_undefined()
+        || is_basedpython_implicit_typing_name(name)
+        // the implicit basedpython names that have no stub to resolve through
+        || matches!(name, "Character" | "Some")
+}
+
+#[cfg(test)]
+mod tests {
+    use ruff_db::files::system_path_to_file;
+    use ruff_db::system::DbWithWritableSystem as _;
+    use ty_python_core::global_scope;
+
+    use crate::db::tests::setup_db;
+
+    use super::{claimed_by_lexical_scope, claimed_by_name_resolution};
+
+    /// the two gates must disagree on *exactly* the implicitly-available names, so
+    /// that a future edit cannot quietly collapse them into one
+    #[test]
+    fn the_gates_differ_only_on_implicitly_available_names() {
+        let mut db = setup_db();
+        db.write_file("/src/a.by", "x = 1\n").unwrap();
+        let file = system_path_to_file(&db, "/src/a.by").unwrap();
+        let scope = global_scope(&db, file);
+
+        // a binding and a builtin: both gates own these
+        for name in ["x", "int"] {
+            assert!(claimed_by_lexical_scope(&db, file, scope, name), "{name}");
+            assert!(claimed_by_name_resolution(&db, file, scope, name), "{name}");
+        }
+
+        // a name nothing claims: both gates leave it for the fallbacks
+        for name in ["nonesuch", "Red"] {
+            assert!(!claimed_by_lexical_scope(&db, file, scope, name), "{name}");
+            assert!(
+                !claimed_by_name_resolution(&db, file, scope, name),
+                "{name}"
+            );
+        }
+
+        // an implicit module global is *not* part of the difference: the shared
+        // builtins lookup already falls back to `types.ModuleType`, so the wider
+        // gate's own module-global check only ever repeats an answer it has
+        for name in ["__name__", "__spec__", "__debug__", "__file__"] {
+            assert!(claimed_by_lexical_scope(&db, file, scope, name), "{name}");
+        }
+
+        // the whole of the difference: the basedpython implicit `typing` names, and
+        // the two implicit names that have no stub to resolve through
+        for name in ["Optional", "Self", "Sequence", "Character", "Some"] {
+            assert!(!claimed_by_lexical_scope(&db, file, scope, name), "{name}");
+            assert!(claimed_by_name_resolution(&db, file, scope, name), "{name}");
+        }
+    }
+}
diff --git a/crates/ty_python_semantic/src/types/receivers.rs b/crates/ty_python_semantic/src/types/receivers.rs
index 82d5e343da..a99b77cd1d 100644
--- a/crates/ty_python_semantic/src/types/receivers.rs
+++ b/crates/ty_python_semantic/src/types/receivers.rs
@@ -12,9 +12,12 @@
 //!   receiver's members are in scope unqualified (`imag` for an `int` receiver)
 //!   and the receiver itself is spelled `self`
 //!
-//! both are *last* fallbacks: a declared member, and any name bound anywhere in
-//! the lexical chain, keeps its ordinary meaning. that is what makes the forms
-//! purely additive — nothing that resolves today changes meaning
+//! both are *last* fallbacks: a declared member, and any name something else
+//! already claims, keeps its ordinary meaning. that is what makes the forms
+//! purely additive — nothing that resolves today changes meaning. the block form
+//! gates on [`claimed_by_name_resolution`], the wider of the two shared
+//! [name-fallback](crate::types::name_fallback) gates, because the transpiler
+//! asks it about a raw name with no fallback chain behind it
 //!
 //! [trailing lambda]: crate::types::trailing_lambda
 
@@ -24,10 +27,8 @@ use ty_python_core::scope::{ScopeId, ScopeKind};
 use ty_python_core::{place_table, semantic_index};
 
 use crate::Db;
-use crate::place::{
-    ConsideredDefinitions, builtins_symbol, is_basedpython_implicit_typing_name,
-    module_type_implicit_global_symbol, symbol,
-};
+use crate::place::{ConsideredDefinitions, symbol};
+use crate::types::name_fallback::claimed_by_name_resolution;
 use crate::types::signatures::{Parameters, Signature};
 use crate::types::{Type, TypeContext, infer_expression_types};
 
@@ -147,7 +148,7 @@ pub(crate) fn implicit_receiver_name<'db>(
     name: &str,
 ) -> Option<ImplicitReceiverName<'db>> {
     let receiver = trailing_lambda_scope_receiver(db, file, scope)?;
-    if resolves_elsewhere(db, file, scope, name) {
+    if claimed_by_name_resolution(db, file, scope, name) {
         return None;
     }
     if name == "self" {
@@ -189,31 +190,3 @@ fn trailing_lambda_scope_receiver<'db>(
     }
     None
 }
-
-/// whether `name` resolves to anything other than a receiver member at `scope`.
-///
-/// This mirrors the fallback chain of an ordinary name load, deliberately erring
-/// towards "yes": a name this misses would resolve as something else while the
-/// transpiler — which re-derives the rewrite from this same answer — lowered it
-/// as a receiver member. The scope walk follows python's own rules (class scopes
-/// are not visible from a nested scope), matching the free-variable walk of a
-/// name load.
-fn resolves_elsewhere(db: &dyn Db, file: File, scope: ScopeId<'_>, name: &str) -> bool {
-    let index = semantic_index(db, file);
-    for (ancestor_id, _) in index.visible_ancestor_scopes(scope.file_scope_id(db)) {
-        let ancestor_scope = ancestor_id.to_scope_id(db, file);
-        if place_table(db, ancestor_scope)
-            .symbol_by_name(name)
-            .is_some_and(|symbol| symbol.is_bound() || symbol.is_declared())
-        {
-            return true;
-        }
-    }
-    !builtins_symbol(db, name).place.is_undefined()
-        || !module_type_implicit_global_symbol(db, file, name)
-            .place
-            .is_undefined()
-        || is_basedpython_implicit_typing_name(name)
-        // the implicit basedpython names that have no stub to resolve through
-        || matches!(name, "Character" | "Some")
-}
diff --git a/docs/basedpython/frameworks/django.md b/docs/basedpython/frameworks/django.md
index 9c7630c622..67187cfd07 100644
--- a/docs/basedpython/frameworks/django.md
+++ b/docs/basedpython/frameworks/django.md
@@ -25,6 +25,69 @@ basedpython supports django models. the type checker understands django's unanno
 - lookup kwargs are validated: `filter(name__startswith="x")` checks that `name` is a field and `startswith` is a valid lookup for strings
 - relation traversal in lookups: `filter(author__birthday__lt=date(2000, 1, 1))` follows foreign keys and checks field types
 
+### lookups written as expressions
+
+django's `__` lookups can be written as ordinary expressions:
+
+```by
+Book.objects.filter(author.name == "Ursula", published > date(1970, 1, 1))
+```
+
+→
+
+```python
+Book.objects.filter(author__name="Ursula", published__gt=date(1970, 1, 1))
+```
+
+`filter`, `exclude`, `get` and `aget` take them. a path joins with `__`, so `author.name` traverses the relation and `published.year` is django's date transform, and each operator spells its lookup:
+
+| expression | keyword    |
+| ---------- | ---------- |
+| `a == v`   | `a=v`      |
+| `a > v`    | `a__gt=v`  |
+| `a >= v`   | `a__gte=v` |
+| `a < v`    | `a__lt=v`  |
+| `a <= v`   | `a__lte=v` |
+| `a in v`   | `a__in=v`  |
+
+the leading name is a field, so it is checked and it has a type: `author` is an `Author`, `published` is a `date`, and a segment that names no field is reported exactly as the keyword form's is. the value is checked against the field the same way too.
+
+a `JSONField` holds arbitrary json rather than fields, so a subscript indexes into one — django's key and index transforms:
+
+```by
+Doc.objects.filter(data["key"] == 1, data["a"]["b"] > 2, data[0] == 3)
+```
+
+→
+
+```python
+Doc.objects.filter(data__key=1, data__a__b__gt=2, data__0=3)
+```
+
+a string subscript is an object key, an integer one is an array index, and the operators apply on top of either. every key is legal json, so nothing is reported for one — just as nothing is reported for the keyword form's `filter(data__anything=1)`
+
+resolution is a *last* fallback, so nothing that resolves today changes meaning. a name bound anywhere in the lexical chain — a local, a parameter, a module global, a builtin — keeps it, and the comparison stays an ordinary one the method takes positionally:
+
+```by
+def search(title: str):
+    Book.objects.filter(title == title)   # the parameter, compared to itself
+    Book.objects.filter(id == 1)          # `id` is the builtin — write `pk == 1`
+```
+
+everything else passes through untouched: `filter(Q(a=1) | Q(b=2))`, `filter(**kwargs)`, and an already-written `filter(author__name="x")` all mean what they always did.
+
+an expression that cannot be read as a lookup is left exactly as written, which leaves its leading name an `unresolved-reference` — the feature never quietly changes a query. these are the refusals:
+
+- `!=`. django has no `__` spelling for it: it writes `.exclude(a=1)` or `~Q(a=1)`, both of which change the method being called
+- a chained comparison (`1 < a < 5`), a reversed one (`"x" == title`), or a call on the left (`title.upper() == "X"`)
+- a lookup before an argument that stays positional, and two lookups that would spell the same keyword — python rejects both
+- the `*_or_create` family, whose first positional parameter is `defaults`
+- a subscript on anything but a `JSONField` — `title["k"]` on a `CharField` is a `FieldError` at runtime. `ArrayField` and `HStoreField` carry key and index transforms too, but they are postgres-only and are not read here yet
+- a subscript django cannot be handed as a keyword: a key held in a variable, a slice, a negative index, a key that is not spellable inside an identifier (`data["a b"]`), and one holding the `__` separator
+- a numeric *string* key. django tries `int()` on every segment, so `data__0` is the index — `data[0]` asks for it, and `data["0"]` has no spelling of its own
+- a key that collides with one of django's lookups on `JSONField`: `exact`, `in`, `isnull`, `range`, the comparisons, the string lookups, and the `has_key` family. django reads the last segment of a keyword as a lookup when the field has one by that name, so `data__gt=1` asks for `data > 1` rather than for the key `"gt"`
+- a dot after a subscript (`data["a"].b`). the dotted part of a path names the field; the subscripts index into it
+
 ### class-body field-name lists
 
 several django and drf constructs spell model field paths as a class-body list of plain strings, which the stubs type as `list[str]`. each literal entry is resolved against the model the declaring class names:

From 7064edc472ccc2781f252efafb6199183544517c Mon Sep 17 00:00:00 2001
From: KotlinIsland <65446343+kotlinisland@users.noreply.github.com>
Date: Sat, 8 Aug 2026 21:38:32 +1000
Subject: [PATCH 15/16] fixes
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

go-to-definition on a lookup path's leading name, which alone of its segments had
nothing to resolve to

an editor's own language id is accepted, so the document enters the project at
all: `basedpython` fell through to `LanguageId::Other`, which reported zero
diagnostics *and* contributed no in-memory contents, so every service answered
about the file as last saved

a template rename is no longer refused by any unrelated local function named
`render`, and f2 on an `{% include %}` fragment no longer moves the template

plus two ignored regression tests for a pre-pass rewrite dropping the project db —
a file whose source is rewritten before phase 0 loses project resolution, so an
unrelated enum member silently stops a lookup lowering while `by check` stays
clean
---
 crates/by_transforms/src/lib.rs               |  63 +++
 crates/ty_ide/src/django_template/project.rs  |  48 ++-
 crates/ty_ide/src/django_template/rename.rs   | 104 +++++
 crates/ty_ide/src/django_template/uses.rs     |  11 +-
 crates/ty_ide/src/goto.rs                     |  30 ++
 crates/ty_ide/src/goto_declaration.rs         |  37 +-
 crates/ty_ide/src/goto_definition.rs          | 381 +++++++++++++++++-
 crates/ty_python_semantic/src/lib.rs          |   6 +-
 .../src/types/ide_support.rs                  |  52 +++
 .../ty_server/src/document/text_document.rs   |  48 ++-
 docs/basedpython/frameworks/django.md         |   2 +
 11 files changed, 769 insertions(+), 13 deletions(-)

diff --git a/crates/by_transforms/src/lib.rs b/crates/by_transforms/src/lib.rs
index 4edc021204..030ed44e8e 100644
--- a/crates/by_transforms/src/lib.rs
+++ b/crates/by_transforms/src/lib.rs
@@ -1265,6 +1265,69 @@ mod cross_file {
         );
     }
 
+    /// the same call, in a file that also declares an `enum class`. the enum
+    /// lowering rewrites the source before phase 0, and phase 0 then drops the
+    /// project db because the working source no longer matches the file
+    /// (`transpile_typed_with_map`'s `source_changed` → `project = None`) — so
+    /// every type-aware pass loses cross-module *and* project resolution, and
+    /// this call is left as the broken `f[int](1)`. an unrelated declaration
+    /// elsewhere in the file must not change what a call lowers to.
+    ///
+    /// reordering cannot fix it: phase 0 depends on running against the
+    /// enum-lowered source (`inferred_annotation` skips the `__slots__ = ()`
+    /// the enum lowering re-feeds through the pipeline). the fix is to give
+    /// phase 0 a db that keeps the project's metadata and system while serving
+    /// the rewritten source for this one file — a `System` wrapper passed to
+    /// `ProjectDatabase::fallible`, which needs a capability threaded in from
+    /// the caller that owns the real db
+    #[test]
+    #[ignore = "known defect: a pre-pass rewrite drops the project db for phase 0"]
+    fn cross_module_resolution_survives_an_enum_in_the_same_file() {
+        let db = project_db(&[
+            ("/mod_a.by", "def f[T](t: T) -> T: ...\n"),
+            (
+                "/mod_b.by",
+                "from mod_a import f\n\nenum class Colour:\n    case Red\n\nresult = f[int](1)\n",
+            ),
+        ]);
+        let out = transpile_file(&db, "/mod_b.by", &Config::test_default());
+        assert!(
+            out.contains("result = f(1)"),
+            "an enum elsewhere in the file must not blind cross-module resolution, got:\n{out}"
+        );
+    }
+
+    /// the same defect reached by *qualification* rather than by an enum
+    /// declaration, which is the likelier trigger and the wider one: one
+    /// unqualified member of an enum imported from elsewhere — `return Red`,
+    /// the headline example of context-sensitive resolution — is enough, since
+    /// `qualified_changed` sets `source_changed` on its own
+    ///
+    /// so composing two shipped basedpython features in one file silently
+    /// breaks the second, with a clean `by check` and valid emitted python
+    #[test]
+    #[ignore = "known defect: a pre-pass rewrite drops the project db for phase 0"]
+    fn cross_module_resolution_survives_a_qualified_name_in_the_same_file() {
+        let db = project_db(&[
+            ("/mod_a.by", "def f[T](t: T) -> T: ...\n"),
+            ("/colours.by", "enum class Colour:\n    case Red, Green\n"),
+            (
+                "/mod_b.by",
+                "from mod_a import f\nfrom colours import Colour\n\ndef pick() -> Colour:\n    return Red\n\nresult = f[int](1)\n",
+            ),
+        ]);
+        let out = transpile_file(&db, "/mod_b.by", &Config::test_default());
+        assert!(
+            out.contains("Colour.Red"),
+            "the qualification itself should still happen, got:\n{out}"
+        );
+        assert!(
+            out.contains("result = f(1)"),
+            "a qualified name elsewhere in the file must not blind cross-module \
+             resolution, got:\n{out}"
+        );
+    }
+
     /// an imported *reified* generic function keeps its `[int]` specialization
     /// — the `@generic` wrapper routes it through `__getitem__`. only the
     /// cross-module type tells us `f` reifies `T` (value-position use), so the
diff --git a/crates/ty_ide/src/django_template/project.rs b/crates/ty_ide/src/django_template/project.rs
index 6db4a0d899..dfcefaca1d 100644
--- a/crates/ty_ide/src/django_template/project.rs
+++ b/crates/ty_ide/src/django_template/project.rs
@@ -28,6 +28,7 @@ use ty_module_resolver::{
     Module, ModuleName, file_to_module, resolve_module_confident, resolve_real_module,
 };
 use ty_project::{Db, Project};
+use ty_python_core::definition::DefinitionKind;
 use ty_python_semantic::SemanticModel;
 use ty_python_semantic::django_settings::{self as settings_source, SettingsNaming};
 use ty_python_semantic::types::ide_support::{
@@ -1309,6 +1310,7 @@ fn template_uses_in_file(db: &dyn Db, file: File) -> Box<[NameUse]> {
 
     let parsed = parsed_module(db, file).load(db);
     let mut visitor = TemplateUseVisitor {
+        db,
         file,
         found: Vec::new(),
     };
@@ -1317,12 +1319,46 @@ fn template_uses_in_file(db: &dyn Db, file: File) -> Box<[NameUse]> {
     visitor.found.into_boxed_slice()
 }
 
-struct TemplateUseVisitor {
+/// whether `func` names something that is definitely not django's
+///
+/// a callee is matched by its last segment, so `shortcuts.render` and `render` are
+/// one — and so is a local helper that happens to be called `render`. recording a
+/// use for one of those is worse than missing a real one: a use whose name is not
+/// a literal refuses the whole rename and names the offending line, so one
+/// `def render(target, edit)` anywhere in a project takes template renaming away
+/// from all of it.
+///
+/// so a callee whose definition is positively somewhere other than django is not
+/// one of these functions. anything short of that — a name nothing binds, or an
+/// import whose module could not be resolved, which lands back on the `import`
+/// statement rather than on what it names — leaves the callee as the name says.
+/// refusing a rename is the safe direction; silently rewriting half a project is
+/// not, so only a *positive* answer excludes.
+fn resolves_outside_django(db: &dyn Db, file: File, func: &Expr) -> bool {
+    let definitions = definitions_of(db, file, func);
+    !definitions.is_empty()
+        && definitions.iter().all(|resolved| {
+            resolved.definition().is_some_and(|definition| {
+                // an import that is still an import is one nothing followed
+                !matches!(
+                    definition.kind(db),
+                    DefinitionKind::Import(_)
+                        | DefinitionKind::ImportFrom(_)
+                        | DefinitionKind::ImportFromSubmodule(_)
+                        | DefinitionKind::StarImport(_)
+                ) && file_to_module(db, definition.file(db))
+                    .is_none_or(|module| !is_djangos(db, module))
+            })
+        })
+}
+
+struct TemplateUseVisitor<'db> {
+    db: &'db dyn Db,
     file: File,
     found: Vec<NameUse>,
 }
 
-impl<'ast> Visitor<'ast> for TemplateUseVisitor {
+impl<'ast> Visitor<'ast> for TemplateUseVisitor<'_> {
     fn visit_stmt(&mut self, stmt: &'ast Stmt) {
         // `template_name = "…"` names a template where django reads one, which is
         // the body of a view class
@@ -1346,6 +1382,7 @@ impl<'ast> Visitor<'ast> for TemplateUseVisitor {
             && let Some(template) = call
                 .arguments
                 .find_argument_value(TEMPLATE_NAME_ATTRIBUTE, 1)
+            && !resolves_outside_django(self.db, self.file, &call.func)
         {
             self.found.push(NameUse::of(self.file, template));
         }
@@ -1365,6 +1402,7 @@ fn route_uses_in_file(db: &dyn Db, file: File) -> Box<[NameUse]> {
 
     let parsed = parsed_module(db, file).load(db);
     let mut visitor = RouteUseVisitor {
+        db,
         file,
         found: Vec::new(),
     };
@@ -1373,15 +1411,17 @@ fn route_uses_in_file(db: &dyn Db, file: File) -> Box<[NameUse]> {
     visitor.found.into_boxed_slice()
 }
 
-struct RouteUseVisitor {
+struct RouteUseVisitor<'db> {
+    db: &'db dyn Db,
     file: File,
     found: Vec<NameUse>,
 }
 
-impl<'ast> Visitor<'ast> for RouteUseVisitor {
+impl<'ast> Visitor<'ast> for RouteUseVisitor<'_> {
     fn visit_expr(&mut self, expr: &'ast Expr) {
         if let Expr::Call(call) = expr
             && let Some(callee) = callee_name(&call.func)
+            && !resolves_outside_django(self.db, self.file, &call.func)
         {
             if REVERSE_CALLEES.contains(&callee.as_str())
                 && let Some(argument) = call.arguments.find_argument_value(REVERSE_NAME_KEYWORD, 0)
diff --git a/crates/ty_ide/src/django_template/rename.rs b/crates/ty_ide/src/django_template/rename.rs
index f6b2cab864..948194f7ad 100644
--- a/crates/ty_ide/src/django_template/rename.rs
+++ b/crates/ty_ide/src/django_template/rename.rs
@@ -1424,6 +1424,110 @@ mod tests {
         );
     }
 
+    /// an `{% include 'a.html#frag' %}` writes two names in one string, and only
+    /// the first is one this renames. a caret in the fragment used to be answered
+    /// with the *template's* range — a range the caret is not even in — so F2 on
+    /// a fragment renamed the file and moved it
+    #[test]
+    fn a_caret_in_an_includes_fragment_renames_nothing() {
+        let fragment = blog(&[
+            (
+                "blog/templates/blog/list.html",
+                "{% include 'blog/post.html#ca<CURSOR>rd' %}",
+            ),
+            (
+                "blog/templates/blog/post.html",
+                "{% partialdef card %}x{% endpartialdef %}",
+            ),
+        ]);
+
+        assert_eq!(fragment.prepare_rename(), "no rename");
+        assert_eq!(fragment.rename("tile"), ["no rename"]);
+
+        // the path in the same string still renames the template
+        let path = blog(&[
+            (
+                "blog/templates/blog/list.html",
+                "{% include 'blog/po<CURSOR>st.html#card' %}",
+            ),
+            (
+                "blog/templates/blog/post.html",
+                "{% partialdef card %}x{% endpartialdef %}",
+            ),
+        ]);
+
+        assert_eq!(
+            path.prepare_rename(),
+            "rename `blog/post.html`, replacing `blog/post.html`"
+        );
+    }
+
+    /// a callee is matched by its last segment, so a helper of the project's own
+    /// called `render` matched it too — and one of those with a non-literal
+    /// second argument refused every template rename in the project, naming a
+    /// line that has nothing to do with django
+    #[test]
+    fn a_local_function_called_render_does_not_refuse_a_template_rename() {
+        let test = blog(&[
+            ("django/__init__.py", ""),
+            (
+                "django/shortcuts.py",
+                "def render(request, template_name, context=None): ...\n",
+            ),
+            (
+                "blog/edits.py",
+                "
+                def render(target, edit):
+                    return (target, edit)
+
+
+                def apply(changes):
+                    return [render(path, edit) for path, edit in changes]
+                ",
+            ),
+            (
+                "blog/templates/blog/child.html",
+                "{% extends 'blog/p<CURSOR>ost.html' %}",
+            ),
+            ("blog/templates/blog/post.html", "x"),
+        ]);
+
+        assert_eq!(
+            test.prepare_rename(),
+            "rename `blog/post.html`, replacing `blog/post.html`"
+        );
+
+        // django's own still refuses, which is what the exclusion must not cost
+        let refusing = blog(&[
+            ("django/__init__.py", ""),
+            (
+                "django/shortcuts.py",
+                "def render(request, template_name, context=None): ...\n",
+            ),
+            (
+                "blog/views.py",
+                "
+                from django.shortcuts import render
+
+
+                def post(request, chosen):
+                    return render(request, chosen, {})
+                ",
+            ),
+            (
+                "blog/templates/blog/child.html",
+                "{% extends 'blog/p<CURSOR>ost.html' %}",
+            ),
+            ("blog/templates/blog/post.html", "x"),
+        ]);
+
+        assert!(
+            refusing.prepare_rename().contains("worked out at run time"),
+            "got {}",
+            refusing.prepare_rename()
+        );
+    }
+
     #[test]
     fn a_constant_holding_the_template_name_refuses_the_rename() {
         let test = blog(&[
diff --git a/crates/ty_ide/src/django_template/uses.rs b/crates/ty_ide/src/django_template/uses.rs
index 1483ff7808..0fdac214a0 100644
--- a/crates/ty_ide/src/django_template/uses.rs
+++ b/crates/ty_ide/src/django_template/uses.rs
@@ -197,7 +197,16 @@ fn at_template(
             Some((Named::Route(source[range].to_compact_string()), range))
         }
         tag if TEMPLATE_TAGS.contains(&tag) => {
-            let range = strip_fragment(source, first_string(source, arguments, token)?);
+            let contents = first_string(source, arguments, token)?;
+            let range = strip_fragment(source, contents);
+            // the part after the `#` addresses a partial rather than naming the
+            // template, and a partial's name is none of the names renamed here.
+            // answering with the template's range anyway would hand the editor a
+            // range the caret is not in, and rename — and move — the whole file
+            // for a caret that asked about a fragment
+            if range != contents && offset >= range.end() {
+                return None;
+            }
             Some((Named::Template(source[range].to_compact_string()), range))
         }
         _ => None,
diff --git a/crates/ty_ide/src/goto.rs b/crates/ty_ide/src/goto.rs
index 3bcd0d0adc..b969ac180c 100644
--- a/crates/ty_ide/src/goto.rs
+++ b/crates/ty_ide/src/goto.rs
@@ -414,6 +414,10 @@ impl<'db> Definitions<'db> {
     pub(crate) fn iter(&self) -> std::slice::Iter<'_, ResolvedDefinition<'db>> {
         self.0.iter()
     }
+
+    pub(crate) fn is_empty(&self) -> bool {
+        self.0.is_empty()
+    }
 }
 
 impl<'a, 'db> IntoIterator for &'a Definitions<'db> {
@@ -1324,6 +1328,32 @@ fn definitions_for_expression<'db>(
     }
 }
 
+/// basedpython: the definitions of the model field a django lookup expression's
+/// leading name names — `author` in `Book.objects.filter(author.name == "x")`
+///
+/// that name resolves through the lookup DSL rather than through the scope, so
+/// there is no binding for the ordinary resolution to answer with. `None` for
+/// every other target, and for a name in an argument the lookup classifier
+/// refuses, which still means whatever it meant without the DSL
+pub(crate) fn django_lookup_definitions<'db>(
+    model: &SemanticModel<'db>,
+    parsed: &ParsedModuleRef,
+    goto_target: &GotoTarget<'_>,
+) -> Option<Definitions<'db>> {
+    if !matches!(goto_target, GotoTarget::Expression(ExprRef::Name(_))) {
+        return None;
+    }
+    let name = goto_target.range();
+    let covering = covering_node(parsed.syntax().into(), name);
+    // the leading name sits inside the arguments of the call that spells the query
+    let call = covering.ancestors().find_map(|node| match node {
+        AnyNodeRef::ExprCall(call) => Some(call),
+        _ => None,
+    })?;
+    let definitions = ty_python_semantic::definitions_for_django_lookup_root(model, call, name);
+    (!definitions.is_empty()).then(|| Definitions::new(definitions))
+}
+
 fn definitions_for_callable<'db>(
     model: &SemanticModel<'db>,
     call: &ast::ExprCall,
diff --git a/crates/ty_ide/src/goto_declaration.rs b/crates/ty_ide/src/goto_declaration.rs
index 3ffb7bad31..d0786770df 100644
--- a/crates/ty_ide/src/goto_declaration.rs
+++ b/crates/ty_ide/src/goto_declaration.rs
@@ -1,4 +1,4 @@
-use crate::goto::find_goto_target;
+use crate::goto::{django_lookup_definitions, find_goto_target};
 use crate::{Db, NavigationTargets, RangedValue};
 use ruff_db::files::{File, FileRange};
 use ruff_db::parsed::parsed_module;
@@ -20,7 +20,11 @@ pub fn goto_declaration(
     let goto_target = find_goto_target(&model, &module, offset)?;
 
     let declaration_targets = goto_target
-        .definitions(&model, ImportAliasResolution::ResolveAliases)?
+        .definitions(&model, ImportAliasResolution::ResolveAliases)
+        .filter(|definitions| !definitions.is_empty())
+        // basedpython: a django lookup path's leading name declares no binding, so
+        // the field it names is the only declaration there is
+        .or_else(|| django_lookup_definitions(&model, &module, &goto_target))?
         .goto_declaration(&model, &goto_target)?
         .into_navigation_targets(model.db());
 
@@ -2921,6 +2925,35 @@ def ab(a: int, *, c: int): ...
         "#);
     }
 
+    #[test]
+    fn goto_declaration_django_lookup_relation() {
+        // a lookup path's leading name binds nothing, so the field it names is
+        // both its definition and its declaration — the two must agree
+        let test = crate::goto_definition::test::django_lookup_test(
+            r#"
+from blog.models import Book
+
+def q():
+    return Book.objects.filter(auth<CURSOR>or.name == "x")
+"#,
+        );
+
+        assert_snapshot!(test.goto_declaration(), @r#"
+        info[goto-declaration]: Go to declaration
+         --> src/blog/queries.by:5:32
+          |
+        5 |     return Book.objects.filter(author.name == "x")
+          |                                ^^^^^^ Clicking here
+          |
+        info: Found 1 declaration
+          --> src/blog/models.py:10:5
+           |
+        10 |     author = models.ForeignKey(Author, on_delete=models.CASCADE)
+           |     ------
+           |
+        "#);
+    }
+
     impl CursorTest {
         fn goto_declaration(&self) -> String {
             let Some(targets) = salsa::attach(&self.db, || {
diff --git a/crates/ty_ide/src/goto_definition.rs b/crates/ty_ide/src/goto_definition.rs
index 45019b208b..592de2afe6 100644
--- a/crates/ty_ide/src/goto_definition.rs
+++ b/crates/ty_ide/src/goto_definition.rs
@@ -1,5 +1,5 @@
 use crate::django_template::django_string_definition;
-use crate::goto::find_goto_target;
+use crate::goto::{django_lookup_definitions, find_goto_target};
 use crate::{Db, NavigationTargets, RangedValue};
 use ruff_db::files::{File, FileRange};
 use ruff_db::parsed::parsed_module;
@@ -28,7 +28,9 @@ pub fn goto_definition(
     let model = SemanticModel::new(db, file);
     let goto_target = find_goto_target(&model, &module, offset)?;
     let definition_targets = goto_target
-        .definitions(&model, ImportAliasResolution::ResolveAliases)?
+        .definitions(&model, ImportAliasResolution::ResolveAliases)
+        .filter(|definitions| !definitions.is_empty())
+        .or_else(|| django_lookup_definitions(&model, &module, &goto_target))?
         .goto_definition(&model, &goto_target)?
         .into_navigation_targets(model.db());
 
@@ -2724,6 +2726,381 @@ def show(request):
         assert_snapshot!(test.goto_definition(), @"No goto target found");
     }
 
+    /// a django whose model, field and manager classes ty recognizes: the
+    /// `KnownClass` names are only read off a third-party search path, so they
+    /// live in site-packages, and the field classes carry the same
+    /// `_pyi_private_*_type` markers the real stubs pin their specializations
+    /// with
+    ///
+    /// `queries` is written as `blog/queries.by`, since a lookup written as an
+    /// expression is basedpython syntax
+    pub(crate) fn django_lookup_test(queries: &str) -> CursorTest {
+        CursorTest::builder()
+            .with_site_packages()
+            .site_packages("django/__init__.pyi", "")
+            .site_packages("django/db/__init__.pyi", "from django.db import models as models")
+            .site_packages(
+                "django/db/models/__init__.pyi",
+                "from django.db.models.base import Model as Model\n\
+                 from django.db.models.fields import CharField as CharField, DateField as DateField\n\
+                 from django.db.models.fields.json import JSONField as JSONField\n\
+                 from django.db.models.fields.related import CASCADE as CASCADE, ForeignKey as ForeignKey\n\
+                 from django.db.models.manager import Manager as Manager\n\
+                 from django.db.models.query import QuerySet as QuerySet",
+            )
+            .site_packages(
+                "django/db/models/base.pyi",
+                "from typing import Any, ClassVar\n\
+                 from typing_extensions import Self\n\
+                 from django.db.models.manager import Manager\n\
+                 \n\
+                 class Model:\n\
+                 \x20   objects: ClassVar[Manager[Self]]\n\
+                 \x20   pk: Any",
+            )
+            .site_packages(
+                "django/db/models/manager.pyi",
+                "from typing import Any, Generic, TypeVar\n\
+                 from django.db.models.query import QuerySet\n\
+                 \n\
+                 _M = TypeVar(\"_M\")\n\
+                 \n\
+                 class Manager(Generic[_M]):\n\
+                 \x20   def filter(self, *args: Any, **kwargs: Any) -> QuerySet[_M, _M]: ...\n\
+                 \x20   def exclude(self, *args: Any, **kwargs: Any) -> QuerySet[_M, _M]: ...\n\
+                 \x20   def get(self, *args: Any, **kwargs: Any) -> _M: ...\n\
+                 \x20   async def aget(self, *args: Any, **kwargs: Any) -> _M: ...",
+            )
+            .site_packages(
+                "django/db/models/query.pyi",
+                "from typing import Generic, TypeVar\n\
+                 \n\
+                 _M = TypeVar(\"_M\")\n\
+                 _Row = TypeVar(\"_Row\")\n\
+                 \n\
+                 class QuerySet(Generic[_M, _Row]): ...",
+            )
+            .site_packages(
+                "django/db/models/fields/__init__.pyi",
+                "from datetime import date\n\
+                 from typing import Any, Generic, TypeVar\n\
+                 \n\
+                 _ST = TypeVar(\"_ST\")\n\
+                 _GT = TypeVar(\"_GT\")\n\
+                 \n\
+                 class Field(Generic[_ST, _GT]):\n\
+                 \x20   _pyi_private_set_type: Any\n\
+                 \x20   _pyi_private_get_type: Any\n\
+                 \x20   def __init__(self, **kwargs: Any) -> None: ...\n\
+                 \x20   def __get__(self, instance: Any, owner: Any = None) -> _GT: ...\n\
+                 \x20   def __set__(self, instance: Any, value: _ST) -> None: ...\n\
+                 \n\
+                 class CharField(Field[_ST, _GT]):\n\
+                 \x20   _pyi_private_set_type: str\n\
+                 \x20   _pyi_private_get_type: str\n\
+                 \n\
+                 class DateField(Field[_ST, _GT]):\n\
+                 \x20   _pyi_private_set_type: date\n\
+                 \x20   _pyi_private_get_type: date",
+            )
+            .site_packages(
+                "django/db/models/fields/json.pyi",
+                "from typing import Any, TypeVar\n\
+                 from django.db.models.fields import Field\n\
+                 \n\
+                 _ST = TypeVar(\"_ST\")\n\
+                 _GT = TypeVar(\"_GT\")\n\
+                 \n\
+                 class JSONField(Field[_ST, _GT]):\n\
+                 \x20   _pyi_private_set_type: Any\n\
+                 \x20   _pyi_private_get_type: Any",
+            )
+            .site_packages(
+                "django/db/models/fields/related.pyi",
+                "from typing import Any, TypeVar\n\
+                 from django.db.models.fields import Field\n\
+                 \n\
+                 _ST = TypeVar(\"_ST\")\n\
+                 _GT = TypeVar(\"_GT\")\n\
+                 \n\
+                 CASCADE: Any\n\
+                 \n\
+                 class ForeignKey(Field[_ST, _GT]):\n\
+                 \x20   _pyi_private_set_type: Any\n\
+                 \x20   _pyi_private_get_type: Any\n\
+                 \x20   def __init__(self, to: Any, on_delete: Any = ..., **kwargs: Any) -> None: ...",
+            )
+            .source(
+                "blog/models.py",
+                r#"
+from django.db import models
+
+class Author(models.Model):
+    name = models.CharField(max_length=100)
+
+class Book(models.Model):
+    title = models.CharField(max_length=200)
+    published = models.DateField()
+    author = models.ForeignKey(Author, on_delete=models.CASCADE)
+
+class Doc(models.Model):
+    data = models.JSONField()
+"#,
+            )
+            .source("blog/queries.by", queries)
+            .build()
+    }
+
+    #[test]
+    fn goto_definition_django_lookup_relation() {
+        let test = django_lookup_test(
+            r#"
+from blog.models import Book
+
+def q():
+    return Book.objects.filter(auth<CURSOR>or.name == "x")
+"#,
+        );
+
+        assert_snapshot!(test.goto_definition(), @r#"
+        info[goto-definition]: Go to definition
+         --> src/blog/queries.by:5:32
+          |
+        5 |     return Book.objects.filter(author.name == "x")
+          |                                ^^^^^^ Clicking here
+          |
+        info: Found 1 definition
+          --> src/blog/models.py:10:5
+           |
+        10 |     author = models.ForeignKey(Author, on_delete=models.CASCADE)
+           |     ------
+           |
+        "#);
+    }
+
+    #[test]
+    fn goto_definition_django_lookup_segment_after_a_relation() {
+        // the segment after a relation hop resolves against the model the path
+        // traverses into, which the ordinary member resolution already answers
+        let test = django_lookup_test(
+            r#"
+from blog.models import Book
+
+def q():
+    return Book.objects.filter(author.na<CURSOR>me == "x")
+"#,
+        );
+
+        assert_snapshot!(test.goto_definition(), @r#"
+        info[goto-definition]: Go to definition
+         --> src/blog/queries.by:5:39
+          |
+        5 |     return Book.objects.filter(author.name == "x")
+          |                                       ^^^^ Clicking here
+          |
+        info: Found 1 definition
+         --> src/blog/models.py:5:5
+          |
+        5 |     name = models.CharField(max_length=100)
+          |     ----
+          |
+        "#);
+    }
+
+    #[test]
+    fn goto_definition_django_lookup_with_an_operator() {
+        let test = django_lookup_test(
+            r#"
+from blog.models import Book
+
+def q():
+    return Book.objects.filter(publ<CURSOR>ished > 1)
+"#,
+        );
+
+        assert_snapshot!(test.goto_definition(), @"
+        info[goto-definition]: Go to definition
+         --> src/blog/queries.by:5:32
+          |
+        5 |     return Book.objects.filter(published > 1)
+          |                                ^^^^^^^^^ Clicking here
+          |
+        info: Found 1 definition
+         --> src/blog/models.py:9:5
+          |
+        9 |     published = models.DateField()
+          |     ---------
+          |
+        ");
+    }
+
+    #[test]
+    fn goto_definition_django_lookup_on_exclude() {
+        let test = django_lookup_test(
+            r#"
+from blog.models import Book
+
+def q():
+    return Book.objects.exclude(ti<CURSOR>tle == "x")
+"#,
+        );
+
+        assert_snapshot!(test.goto_definition(), @r#"
+        info[goto-definition]: Go to definition
+         --> src/blog/queries.by:5:33
+          |
+        5 |     return Book.objects.exclude(title == "x")
+          |                                 ^^^^^ Clicking here
+          |
+        info: Found 1 definition
+         --> src/blog/models.py:8:5
+          |
+        8 |     title = models.CharField(max_length=200)
+          |     -----
+          |
+        "#);
+    }
+
+    #[test]
+    fn goto_definition_django_lookup_json_field() {
+        let test = django_lookup_test(
+            r#"
+from blog.models import Doc
+
+def q():
+    return Doc.objects.get(da<CURSOR>ta["key"] == 1)
+"#,
+        );
+
+        assert_snapshot!(test.goto_definition(), @r#"
+        info[goto-definition]: Go to definition
+         --> src/blog/queries.by:5:28
+          |
+        5 |     return Doc.objects.get(data["key"] == 1)
+          |                            ^^^^ Clicking here
+          |
+        info: Found 1 definition
+          --> src/blog/models.py:13:5
+           |
+        13 |     data = models.JSONField()
+           |     ----
+           |
+        "#);
+    }
+
+    #[test]
+    fn goto_definition_django_lookup_json_key() {
+        // a json key is an arbitrary string that nothing declares
+        let test = django_lookup_test(
+            r#"
+from blog.models import Doc
+
+def q():
+    return Doc.objects.filter(data["k<CURSOR>ey"] == 1)
+"#,
+        );
+
+        assert_snapshot!(test.goto_definition(), @"No goto target found");
+    }
+
+    #[test]
+    fn goto_definition_django_lookup_pk() {
+        // `pk` names no field of the model — django declares it on `Model`, and
+        // that declaration is the only one there is. it is deliberately not
+        // resolved to whichever field the primary key happens to be: that field
+        // is synthesized when the model declares none, and guessing at it would
+        // send the editor somewhere the source never says
+        let test = django_lookup_test(
+            r#"
+from blog.models import Book
+
+def q():
+    return Book.objects.filter(p<CURSOR>k == 1)
+"#,
+        );
+
+        assert_snapshot!(test.goto_definition(), @"
+        info[goto-definition]: Go to definition
+         --> src/blog/queries.by:5:32
+          |
+        5 |     return Book.objects.filter(pk == 1)
+          |                                ^^ Clicking here
+          |
+        info: Found 1 definition
+         --> site-packages/django/db/models/base.pyi:7:5
+          |
+        7 |     pk: Any
+          |     --
+          |
+        ");
+    }
+
+    #[test]
+    fn goto_definition_django_lookup_refused_operator() {
+        // `!=` spells no lookup, so the name is not a field path and means
+        // whatever it meant without the DSL — here, nothing
+        let test = django_lookup_test(
+            r#"
+from blog.models import Book
+
+def q():
+    return Book.objects.filter(ti<CURSOR>tle != "x")
+"#,
+        );
+
+        assert_snapshot!(test.goto_definition(), @"No goto target found");
+    }
+
+    #[test]
+    fn goto_definition_django_lookup_shadowed_by_a_local() {
+        // a name something else already claims is not a lookup path at all
+        let test = django_lookup_test(
+            r#"
+from blog.models import Book
+
+def q():
+    title = "x"
+    return Book.objects.filter(ti<CURSOR>tle == "x")
+"#,
+        );
+
+        assert_snapshot!(test.goto_definition(), @r#"
+        info[goto-definition]: Go to definition
+         --> src/blog/queries.by:6:32
+          |
+        6 |     return Book.objects.filter(title == "x")
+          |                                ^^^^^ Clicking here
+          |
+        info: Found 1 definition
+         --> src/blog/queries.by:5:5
+          |
+        5 |     title = "x"
+          |     -----
+          |
+        "#);
+    }
+
+    #[test]
+    fn goto_definition_django_lookup_in_a_python_file() {
+        // the DSL is basedpython's; in a python file the comparison is an
+        // ordinary one against an undefined name
+        let test = CursorTest::builder()
+            .with_site_packages()
+            .site_packages("django/__init__.pyi", "")
+            .source(
+                "main.py",
+                r#"
+class Book: ...
+
+def q():
+    return Book.objects.filter(auth<CURSOR>or.name == "x")
+"#,
+            )
+            .build();
+
+        assert_snapshot!(test.goto_definition(), @"No goto target found");
+    }
+
     impl CursorTest {
         fn goto_definition(&self) -> String {
             let Some(targets) = salsa::attach(&self.db, || {
diff --git a/crates/ty_python_semantic/src/lib.rs b/crates/ty_python_semantic/src/lib.rs
index 20a355c926..77d7b8de75 100644
--- a/crates/ty_python_semantic/src/lib.rs
+++ b/crates/ty_python_semantic/src/lib.rs
@@ -46,9 +46,9 @@ pub use types::conversions::{ConversionImport, ConversionInfo};
 pub use types::extensions::{ExtensionAttributeInfo, ExtensionMemberKind};
 pub use types::ide_support::{
     ImportAliasResolution, ResolvedDefinition, TypeHierarchyClass, definitions_for_attribute,
-    definitions_for_bin_op, definitions_for_imported_symbol, definitions_for_name,
-    definitions_for_unary_op, map_stub_definition, type_hierarchy_prepare, type_hierarchy_subtypes,
-    type_hierarchy_supertypes,
+    definitions_for_bin_op, definitions_for_django_lookup_root, definitions_for_imported_symbol,
+    definitions_for_name, definitions_for_unary_op, map_stub_definition, type_hierarchy_prepare,
+    type_hierarchy_subtypes, type_hierarchy_supertypes,
 };
 pub use types::reified_infer::{
     ArgVariance, ErasedTargetReason, ErasedUnion, ParametricIsPlan, ProtocolMemberCheck,
diff --git a/crates/ty_python_semantic/src/types/ide_support.rs b/crates/ty_python_semantic/src/types/ide_support.rs
index 5fe52d6035..6c9e6f104b 100644
--- a/crates/ty_python_semantic/src/types/ide_support.rs
+++ b/crates/ty_python_semantic/src/types/ide_support.rs
@@ -330,6 +330,58 @@ pub fn definitions_for_attribute<'db>(
     resolved
 }
 
+/// basedpython: the declarations of the model field the leading name of a django
+/// lookup expression names — `author` in `Book.objects.filter(author.name == "x")`
+///
+/// that name is a field path rather than a value, so nothing in the enclosing
+/// scope binds it and the ordinary resolution has nothing to answer with. every
+/// segment after it is a member access on the model the path traverses into, and
+/// resolves the ordinary way already
+///
+/// empty unless `name` is the range of the leading name of an argument the lookup
+/// classifier accepted: an argument it refuses keeps whatever it meant without
+/// the DSL, and a field the model declares nowhere — `pk`, an `<fk>_id` attname —
+/// has no declaration to navigate to
+pub fn definitions_for_django_lookup_root<'db>(
+    model: &SemanticModel<'db>,
+    call: &ast::ExprCall,
+    name: TextRange,
+) -> Vec<ResolvedDefinition<'db>> {
+    let db = model.db();
+    let file = model.file();
+    if !file.source_type(db).is_basedpython() {
+        return Vec::new();
+    }
+    let Some(callee) = call.func.inferred_type(model) else {
+        return Vec::new();
+    };
+    let Some(queried) = django::lookup_call_model(db, callee) else {
+        return Vec::new();
+    };
+    let Some(scope) = model.scope(AnyNodeRef::from(call)) else {
+        return Vec::new();
+    };
+    let lookups = django::lookup_expressions(
+        db,
+        file,
+        scope.to_scope_id(db, file),
+        queried,
+        &call.arguments,
+    );
+    let Some(root) = lookups
+        .iter()
+        .filter_map(|lookup| lookup.path.first()?.as_name_expr())
+        .find(|root| root.range() == name)
+    else {
+        return Vec::new();
+    };
+    definitions_for_attribute_in_class_hierarchy(
+        &ClassLiteral::Static(queried),
+        model,
+        root.id.as_str(),
+    )
+}
+
 /// Returns the descriptor object type for an attribute expression `x.y`, without invoking the
 /// descriptor protocol. This corresponds to `inspect.getattr_static(x, "y")` at the type level.
 pub fn static_member_type_for_attribute<'db>(
diff --git a/crates/ty_server/src/document/text_document.rs b/crates/ty_server/src/document/text_document.rs
index 34f36cb61c..8eb4d42d69 100644
--- a/crates/ty_server/src/document/text_document.rs
+++ b/crates/ty_server/src/document/text_document.rs
@@ -2,6 +2,7 @@ use lsp_types::{
     LanguageKind, TextDocumentContentChangeEvent, TextDocumentContentChangePartial,
     TextDocumentContentChangeWholeDocument, Uri,
 };
+use ruff_python_ast::PySourceType;
 use ruff_source_file::LineIndex;
 
 use crate::PositionEncoding;
@@ -60,13 +61,23 @@ impl LanguageId {
     /// no template services at all — is the honest answer. It is answered
     /// outright, ahead of the path fallback, because a client that says `jinja`
     /// has settled the question that fallback exists to guess at.
+    ///
+    /// Editors disagree about what to call python too — `python3`, `py` and
+    /// `basedpython` are all in use — and [`Self::Other`] is a document the
+    /// server never adds to the project, so an id we do not know would leave a
+    /// `.py` file with no diagnostics and every service reading the file as last
+    /// saved rather than as the client has it. So a path python owns is python,
+    /// exactly as a path django owns is a template.
     pub(crate) fn new(language_id: &LanguageKind, path: &AnySystemPath) -> Self {
         match language_id.as_str() {
-            "python" | "by" => Self::Python,
+            "python" | "by" | "basedpython" => Self::Python,
             "django-html" | "django-txt" | "htmldjango" | "django" => Self::DjangoTemplate,
             "jinja" | "jinja-html" | "jinja2" => Self::Other,
             _ => match path.as_system() {
                 Some(path) if ty_ide::is_django_template_path(path) => Self::DjangoTemplate,
+                Some(path) if PySourceType::try_from_path(path.as_std_path()).is_some() => {
+                    Self::Python
+                }
                 _ => Self::Other,
             },
         }
@@ -238,6 +249,41 @@ mod tests {
         );
     }
 
+    #[test]
+    fn the_editors_python_language_ids_are_python() {
+        for id in ["python", "by", "basedpython"] {
+            assert_eq!(
+                opened("file:///app/mod.by", id),
+                LanguageId::Python,
+                "`{id}` is python"
+            );
+        }
+    }
+
+    #[test]
+    fn a_python_path_is_python_whatever_the_client_calls_it() {
+        // an id we do not know would otherwise leave the file out of the project
+        // entirely: no diagnostics, and every service reading it as last saved
+        for (uri, id) in [
+            ("file:///app/mod.py", "python3"),
+            ("file:///app/mod.py", "py"),
+            ("file:///app/mod.by", "basedpython-lang"),
+            ("file:///app/mod.pyi", ""),
+            ("file:///app/mod.byi", "plaintext"),
+        ] {
+            assert_eq!(
+                opened(uri, id),
+                LanguageId::Python,
+                "`{uri}` called `{id}` is python"
+            );
+        }
+
+        assert_eq!(
+            opened("file:///app/notes.txt", "plaintext"),
+            LanguageId::Other
+        );
+    }
+
     #[test]
     fn an_html_file_under_templates_is_a_django_template_whatever_it_is_called() {
         assert_eq!(
diff --git a/docs/basedpython/frameworks/django.md b/docs/basedpython/frameworks/django.md
index 67187cfd07..c4faa38515 100644
--- a/docs/basedpython/frameworks/django.md
+++ b/docs/basedpython/frameworks/django.md
@@ -52,6 +52,8 @@ Book.objects.filter(author__name="Ursula", published__gt=date(1970, 1, 1))
 
 the leading name is a field, so it is checked and it has a type: `author` is an `Author`, `published` is a `date`, and a segment that names no field is reported exactly as the keyword form's is. the value is checked against the field the same way too.
 
+an editor reads a path as fields too: going to a segment's definition or declaration opens the field it names, so `author` opens `Book.author` and `name` opens `Author.name`. `pk` opens django's own `pk` on `Model` — the only declaration of that name — rather than whichever field the primary key turns out to be, which the model may not declare at all. a json key is an arbitrary string that nothing declares, and a refused expression keeps whatever its name meant without the DSL, so neither leads anywhere
+
 a `JSONField` holds arbitrary json rather than fields, so a subscript indexes into one — django's key and index transforms:
 
 ```by

From a184ca0e0117a35524ea87f5f0417d11762da6a6 Mon Sep 17 00:00:00 2001
From: KotlinIsland <65446343+kotlinisland@users.noreply.github.com>
Date: Sun, 9 Aug 2026 00:08:55 +1000
Subject: [PATCH 16/16] phase 0 keeps the project when a pre-pass rewrote the
 source
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

erased-union reification, name qualification and enum lowering all rewrite the
source before phase 0 runs, and phase 0 then fell back to a bare single-file db
because the working source no longer matched the project file. every
TypeAwarePass lost cross-module *and* project resolution and silently declined
to lower, so an enum declared anywhere in a file broke a django lookup
elsewhere in it — with a clean `by check` and valid emitted python

callers that own a real db now pass a `RebuildProject`: a way to build a second
db over the same project, into which the rewritten source is served for the one
file through `File::source_text_override`. the project's metadata, search paths
and sibling files stay. a caller with no project still gets the single-file db

the rebuilt db has to be a new one rather than a clone: salsa handles cloned
from one db share storage, so the override would be visible through the
caller's own db
---
 Cargo.lock                                    |   1 +
 crates/by_transforms/Cargo.toml               |   1 +
 crates/by_transforms/src/lib.rs               | 176 +++++++++++++-----
 .../src/transforms/context_sensitive.rs       |   2 +-
 .../src/transforms/frameworks.rs              |  11 +-
 .../src/transforms/kw_subscript.rs            |   2 +-
 crates/ty/src/by_commands.rs                  |  70 +++++--
 .../development/how-transpilation-works.md    |  33 +++-
 8 files changed, 224 insertions(+), 72 deletions(-)

diff --git a/Cargo.lock b/Cargo.lock
index d5c02b1493..4f40060dad 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -364,6 +364,7 @@ dependencies = [
  "ruff_python_trivia",
  "ruff_source_file",
  "ruff_text_size",
+ "salsa",
  "tempfile",
  "thin-vec",
  "ty_project",
diff --git a/crates/by_transforms/Cargo.toml b/crates/by_transforms/Cargo.toml
index 989c66cf93..1a6432d768 100644
--- a/crates/by_transforms/Cargo.toml
+++ b/crates/by_transforms/Cargo.toml
@@ -21,6 +21,7 @@ ruff_python_stdlib = { workspace = true }
 ruff_python_trivia = { workspace = true }
 ruff_source_file = { workspace = true }
 ruff_text_size = { workspace = true }
+salsa = { workspace = true }
 thin-vec = { workspace = true }
 ty_project = { workspace = true, features = ["testing"] }
 ty_python_core = { workspace = true }
diff --git a/crates/by_transforms/src/lib.rs b/crates/by_transforms/src/lib.rs
index 030ed44e8e..c23ab0a00a 100644
--- a/crates/by_transforms/src/lib.rs
+++ b/crates/by_transforms/src/lib.rs
@@ -9,12 +9,13 @@ pub use config::{Config, PythonVersion, SoundnessPositions};
 use std::collections::{BTreeSet, HashSet};
 
 use ruff_db::files::{File, system_path_to_file};
-use ruff_db::system::{DbWithWritableSystem as _, SystemPathBuf};
-use ruff_diagnostics::{Edit, Fix, IsolationLevel};
+use ruff_db::system::{DbWithWritableSystem as _, SystemPath, SystemPathBuf};
+use ruff_diagnostics::{Edit, Fix, IsolationLevel, SourceMap};
 use ruff_python_ast::Stmt;
 use ruff_python_ast::visitor::Visitor;
 use ruff_source_file::LineRanges;
 use ruff_text_size::{Ranged, TextSize};
+use salsa::Setter as _;
 use ty_project::{ProjectMetadata, TestDb};
 
 use type_info::TypeInfo;
@@ -34,6 +35,47 @@ pub(crate) fn make_in_memory_db(source: &str) -> (TestDb, File) {
     (db, file)
 }
 
+/// A caller-supplied capability to build a *second* database over the same
+/// project as the one it hands to [`transpile_typed`].
+///
+/// A pre-pass — erased-union reification, name qualification, enum lowering —
+/// can rewrite the source before phase 0 runs, and phase 0's type-aware passes
+/// must query a db whose contents are the source they walk. Given this
+/// capability the transpiler keeps the real project (its metadata, search paths
+/// and sibling files) and serves only the rewritten file from memory; without
+/// it, phase 0 falls back to a single-file db that resolves nothing outside the
+/// file — correct, but blind to imports.
+///
+/// The database must be a *new* one, not a clone: salsa handles cloned from one
+/// database share storage, so the source override would be visible through the
+/// caller's own db.
+pub type RebuildProject<'a> = &'a dyn Fn() -> Option<Box<dyn ty_python_semantic::Db>>;
+
+/// A rebuilt project db in which one file reads as rewritten source.
+struct Overlaid {
+    db: Box<dyn ty_python_semantic::Db>,
+    file: File,
+}
+
+/// Rebuild the project db and serve `source` as the contents of `path`, so
+/// type-aware passes see the rewritten source with the project still around it.
+///
+/// Returns `None` when the caller supplied no [`RebuildProject`], the rebuild
+/// failed, or the rebuilt db doesn't hold `path` — every one of which leaves the
+/// single-file fallback in place.
+fn overlay_rewritten_source(
+    rebuild: Option<RebuildProject<'_>>,
+    path: &SystemPath,
+    source: &str,
+) -> Option<Overlaid> {
+    let mut db = rebuild?()?;
+    let file = system_path_to_file(&*db, path).ok()?;
+    let text = ruff_db::source::source_text(&*db, file)
+        .with_text(source.to_owned(), &SourceMap::default());
+    file.set_source_text_override(&mut *db).to(Some(text));
+    Some(Overlaid { db, file })
+}
+
 /// Qualify every context-sensitively resolved name (`a: Color = Red` →
 /// `Color.Red`) against the *original* source — before the enum lowering
 /// rewrites `enum class` to python, so ty resolves the same source it checks.
@@ -172,8 +214,9 @@ pub fn transpile_typed(
     db: &dyn ty_python_semantic::Db,
     file: File,
     config: &Config,
+    rebuild: Option<RebuildProject<'_>>,
 ) -> Result<String, TranspileError> {
-    transpile_typed_with_map(db, file, config).map(|(out, _)| out)
+    transpile_typed_with_map(db, file, config, rebuild).map(|(out, _)| out)
 }
 
 /// Like [`transpile_typed`] but also returns a line table mapping each output
@@ -188,6 +231,7 @@ pub fn transpile_typed_with_map(
     db: &dyn ty_python_semantic::Db,
     file: File,
     config: &Config,
+    rebuild: Option<RebuildProject<'_>>,
 ) -> Result<(String, Vec<Option<u32>>), TranspileError> {
     let source_ref = ruff_db::source::source_text(db, file);
     let original_source = source_ref.as_str();
@@ -237,13 +281,22 @@ pub fn transpile_typed_with_map(
     let enum_changed = matches!(enum_lowered.output, std::borrow::Cow::Owned(_));
     let source_changed = reified_changed || qualified_changed || enum_changed;
 
-    // phase 0: AST passes. with the project db (no enums) type-aware passes
-    // resolve cross-module imports; `phase0_map` maps spliced lines → working
-    // (post-enum) lines
-    let project = if source_changed {
-        None
+    // phase 0: AST passes. type-aware passes resolve cross-module imports from
+    // the project db; when a pre-pass rewrote the source, that db is rebuilt
+    // over the rewritten text rather than given up, so an enum or a qualified
+    // name elsewhere in the file doesn't blind them. `phase0_map` maps spliced
+    // lines → working (post-enum) lines
+    let overlaid = if source_changed {
+        file.path(db)
+            .as_system_path()
+            .and_then(|path| overlay_rewritten_source(rebuild, path, working_source))
     } else {
-        Some((db, file))
+        None
+    };
+    let project = match &overlaid {
+        Some(overlaid) => Some((&*overlaid.db, overlaid.file)),
+        None if source_changed => None,
+        None => Some((db, file)),
     };
     let (spliced, ast_errors, phase0_map) =
         transforms::ast_driver::run_against_source(working_source, config, project);
@@ -1227,7 +1280,25 @@ mod cross_file {
     use ruff_db::files::system_path_to_file;
     use ty_project::{ProjectMetadata, TestDb};
 
-    fn project_db(files: &[(&str, &str)]) -> TestDb {
+    /// a project db over `files`, keeping the file list so the project can be
+    /// built a second time — the [`RebuildProject`] capability a real caller
+    /// supplies, for when a pre-pass rewrites the source
+    struct Project {
+        files: Vec<(String, String)>,
+        db: TestDb,
+    }
+
+    impl Project {
+        fn db(&self) -> &TestDb {
+            &self.db
+        }
+
+        fn rebuild(&self) -> Box<dyn ty_python_semantic::Db> {
+            Box::new(build_db(&self.files))
+        }
+    }
+
+    fn build_db(files: &[(String, String)]) -> TestDb {
         let mut db = TestDb::new(ProjectMetadata::new(
             ruff_python_ast::name::Name::new_static(""),
             SystemPathBuf::from("/"),
@@ -1239,9 +1310,19 @@ mod cross_file {
         db
     }
 
-    fn transpile_file(db: &TestDb, path: &str, config: &Config) -> String {
-        let file = system_path_to_file(db, path).expect("file not in db");
-        transpile_typed(db, file, config).expect("transpile failed")
+    fn project_db(files: &[(&str, &str)]) -> Project {
+        let files: Vec<(String, String)> = files
+            .iter()
+            .map(|(path, src)| ((*path).to_owned(), (*src).to_owned()))
+            .collect();
+        let db = build_db(&files);
+        Project { files, db }
+    }
+
+    fn transpile_file(project: &Project, path: &str, config: &Config) -> String {
+        let file = system_path_to_file(project.db(), path).expect("file not in db");
+        let rebuild = || Some(project.rebuild());
+        transpile_typed(project.db(), file, config, Some(&rebuild)).expect("transpile failed")
     }
 
     /// `f[int](1)` must lower to `f(1)` only because ty resolves the imported
@@ -1250,11 +1331,11 @@ mod cross_file {
     /// single-file path can't see `f` and would leave the broken `f[int](1)`.
     #[test]
     fn generic_call_stripped_via_imported_function() {
-        let db = project_db(&[
+        let project = project_db(&[
             ("/mod_a.by", "def f[T](t: T) -> T: ...\n"),
             ("/mod_b.by", "from mod_a import f\nresult = f[int](1)\n"),
         ]);
-        let out = transpile_file(&db, "/mod_b.by", &Config::test_default());
+        let out = transpile_file(&project, "/mod_b.by", &Config::test_default());
         assert!(
             out.contains("result = f(1)"),
             "imported generic function should strip type args, got:\n{out}"
@@ -1281,16 +1362,15 @@ mod cross_file {
     /// `ProjectDatabase::fallible`, which needs a capability threaded in from
     /// the caller that owns the real db
     #[test]
-    #[ignore = "known defect: a pre-pass rewrite drops the project db for phase 0"]
     fn cross_module_resolution_survives_an_enum_in_the_same_file() {
-        let db = project_db(&[
+        let project = project_db(&[
             ("/mod_a.by", "def f[T](t: T) -> T: ...\n"),
             (
                 "/mod_b.by",
                 "from mod_a import f\n\nenum class Colour:\n    case Red\n\nresult = f[int](1)\n",
             ),
         ]);
-        let out = transpile_file(&db, "/mod_b.by", &Config::test_default());
+        let out = transpile_file(&project, "/mod_b.by", &Config::test_default());
         assert!(
             out.contains("result = f(1)"),
             "an enum elsewhere in the file must not blind cross-module resolution, got:\n{out}"
@@ -1306,9 +1386,8 @@ mod cross_file {
     /// so composing two shipped basedpython features in one file silently
     /// breaks the second, with a clean `by check` and valid emitted python
     #[test]
-    #[ignore = "known defect: a pre-pass rewrite drops the project db for phase 0"]
     fn cross_module_resolution_survives_a_qualified_name_in_the_same_file() {
-        let db = project_db(&[
+        let project = project_db(&[
             ("/mod_a.by", "def f[T](t: T) -> T: ...\n"),
             ("/colours.by", "enum class Colour:\n    case Red, Green\n"),
             (
@@ -1316,7 +1395,7 @@ mod cross_file {
                 "from mod_a import f\nfrom colours import Colour\n\ndef pick() -> Colour:\n    return Red\n\nresult = f[int](1)\n",
             ),
         ]);
-        let out = transpile_file(&db, "/mod_b.by", &Config::test_default());
+        let out = transpile_file(&project, "/mod_b.by", &Config::test_default());
         assert!(
             out.contains("Colour.Red"),
             "the qualification itself should still happen, got:\n{out}"
@@ -1334,7 +1413,7 @@ mod cross_file {
     /// single-file path can't make this call
     #[test]
     fn imported_reified_function_call_site_preserved() {
-        let db = project_db(&[
+        let project = project_db(&[
             (
                 "/mod_a.by",
                 "def f[T](t: object) -> bool:\n    return isinstance(t, T)\n",
@@ -1345,7 +1424,7 @@ mod cross_file {
             min_version: PythonVersion::PY312,
             ..Config::test_default()
         };
-        let out = transpile_file(&db, "/mod_b.by", &config);
+        let out = transpile_file(&project, "/mod_b.by", &config);
         assert!(
             out.contains("f[int](1)"),
             "reified call site must keep its type args, got:\n{out}"
@@ -1357,14 +1436,14 @@ mod cross_file {
     /// a class, not a function.
     #[test]
     fn imported_class_constructor_preserved() {
-        let db = project_db(&[
+        let project = project_db(&[
             (
                 "/mod_a.by",
                 "class Box[T]:\n    def __init__(self, t: T): ...\n",
             ),
             ("/mod_b.by", "from mod_a import Box\nb = Box[int](1)\n"),
         ]);
-        let out = transpile_file(&db, "/mod_b.by", &Config::test_default());
+        let out = transpile_file(&project, "/mod_b.by", &Config::test_default());
         assert!(
             out.contains("Box[int](1)"),
             "imported generic constructor must keep its type args, got:\n{out}"
@@ -1376,7 +1455,7 @@ mod cross_file {
     /// function and emits its precise import. the surface stays `import ext`
     #[test]
     fn imported_extension_rewrites_call_and_adds_import() {
-        let db = project_db(&[
+        let project = project_db(&[
             (
                 "/ext.by",
                 "extension list:\n    def second(self) -> Element:\n        return self[1]\n",
@@ -1386,7 +1465,7 @@ mod cross_file {
                 "import ext\n\nxs = [1, 2, 3]\nprint(xs.second())\n",
             ),
         ]);
-        let out = transpile_file(&db, "/main.by", &Config::test_default());
+        let out = transpile_file(&project, "/main.by", &Config::test_default());
         assert!(
             out.contains("from ext import _by_ext__list__second"),
             "backing-function import should be emitted, got:\n{out}"
@@ -1396,7 +1475,7 @@ mod cross_file {
             "call should be rewritten, got:\n{out}"
         );
         // the defining module lowers the block itself
-        let ext_out = transpile_file(&db, "/ext.by", &Config::test_default());
+        let ext_out = transpile_file(&project, "/ext.by", &Config::test_default());
         assert!(
             ext_out.contains("def _by_ext__list__second(self):"),
             "defining module should lower the block, got:\n{ext_out}"
@@ -1409,7 +1488,7 @@ mod cross_file {
     /// the using module constructs it — so the two files must agree exactly
     #[test]
     fn imported_implementation_wraps_argument_and_adds_import() {
-        let db = project_db(&[
+        let project = project_db(&[
             (
                 "/iface.by",
                 "abstract class A:\n    abstract def f(self) -> int: ...\n\nclass B:\n    a: int = 3\n",
@@ -1423,7 +1502,7 @@ mod cross_file {
                 "import adapters\nfrom iface import A, B\n\ndef takes_a(a: A) -> int:\n    return a.f()\n\nb = B()\ntakes_a(b)\n",
             ),
         ]);
-        let out = transpile_file(&db, "/main.by", &Config::test_default());
+        let out = transpile_file(&project, "/main.by", &Config::test_default());
         assert!(
             out.contains("from adapters import _by_impl__A__B"),
             "witness import should be emitted, got:\n{out}"
@@ -1433,7 +1512,7 @@ mod cross_file {
             "argument should be wrapped, got:\n{out}"
         );
         // the defining module emits the class under the same name
-        let adapters_out = transpile_file(&db, "/adapters.by", &Config::test_default());
+        let adapters_out = transpile_file(&project, "/adapters.by", &Config::test_default());
         assert!(
             adapters_out.contains("class _by_impl__A__B(_by_Implementation, A):"),
             "defining module should emit the witness class, got:\n{adapters_out}"
@@ -1446,7 +1525,7 @@ mod cross_file {
     /// itself — that import is the whole difference from the single-file case
     #[test]
     fn imported_from_converts_and_imports_the_target() {
-        let db = project_db(&[
+        let project = project_db(&[
             (
                 "/temps.by",
                 "class Celsius:\n    degrees: float = 0.0\n\n\
@@ -1459,7 +1538,7 @@ mod cross_file {
                 "from temps import Celsius, report\n\nreport(Celsius())\n",
             ),
         ]);
-        let out = transpile_file(&db, "/main.by", &Config::test_default());
+        let out = transpile_file(&project, "/main.by", &Config::test_default());
         assert!(
             out.contains("from temps import Fahrenheit as _by_conv__Fahrenheit"),
             "the target class should be imported under its alias, got:\n{out}"
@@ -1475,7 +1554,7 @@ mod cross_file {
     /// rebind whatever this file already means by it
     #[test]
     fn an_already_imported_target_still_uses_its_alias() {
-        let db = project_db(&[
+        let project = project_db(&[
             (
                 "/temps.by",
                 "class Celsius:\n    degrees: float = 0.0\n\n\
@@ -1488,7 +1567,7 @@ mod cross_file {
                  def report(t: Fahrenheit) -> None: ...\n\nreport(Celsius())\n",
             ),
         ]);
-        let out = transpile_file(&db, "/main.by", &Config::test_default());
+        let out = transpile_file(&project, "/main.by", &Config::test_default());
         assert!(
             out.contains("report(_by_conv__Fahrenheit.__from__(Celsius()))"),
             "argument should be converted through the alias, got:\n{out}"
@@ -1504,7 +1583,7 @@ mod cross_file {
     /// the call would reach the wrong object at runtime
     #[test]
     fn a_local_class_of_the_same_name_does_not_capture_the_conversion() {
-        let db = project_db(&[
+        let project = project_db(&[
             (
                 "/temps.by",
                 "class Celsius:\n    degrees: float = 0.0\n\n\
@@ -1518,7 +1597,7 @@ mod cross_file {
                  class Fahrenheit:\n    unrelated: int = 0\n\nreport(Celsius())\n",
             ),
         ]);
-        let out = transpile_file(&db, "/main.by", &Config::test_default());
+        let out = transpile_file(&project, "/main.by", &Config::test_default());
         assert!(
             out.contains("from temps import Fahrenheit as _by_conv__Fahrenheit"),
             "the alias keeps the local class intact, got:\n{out}"
@@ -1535,7 +1614,7 @@ mod cross_file {
     /// (`target/mod.by` → `target.mod` for the checker, `mod` at runtime)
     #[test]
     fn an_imported_witness_is_spelled_as_the_file_imports_it() {
-        let db = project_db(&[
+        let project = project_db(&[
             (
                 "/nested/iface.by",
                 "abstract class A:\n    abstract def f(self) -> int: ...\n\nclass B:\n    a: int = 3\n",
@@ -1549,7 +1628,7 @@ mod cross_file {
                 "import adapters\nfrom iface import A, B\n\ndef takes_a(x: A) -> int:\n    return x.f()\n\nb = B()\ntakes_a(b)\n",
             ),
         ]);
-        let out = transpile_file(&db, "/nested/main.by", &Config::test_default());
+        let out = transpile_file(&project, "/nested/main.by", &Config::test_default());
         assert!(
             out.contains("from adapters import _by_impl__A__B"),
             "the import must use the file's own spelling, got:\n{out}"
@@ -1564,7 +1643,7 @@ mod cross_file {
     /// must keep the dots
     #[test]
     fn a_relatively_imported_witness_keeps_its_dots() {
-        let db = project_db(&[
+        let project = project_db(&[
             ("/pkg/__init__.by", "\n"),
             (
                 "/pkg/iface.by",
@@ -1579,7 +1658,7 @@ mod cross_file {
                 "from .adapters import A\nfrom .iface import B\n\ndef takes_a(x: A) -> int:\n    return x.f()\n\ndef main():\n    takes_a(B())\n",
             ),
         ]);
-        let out = transpile_file(&db, "/pkg/main.by", &Config::test_default());
+        let out = transpile_file(&project, "/pkg/main.by", &Config::test_default());
         assert!(
             out.contains("from .adapters import _by_impl__A__B"),
             "the relative spelling must be kept, got:\n{out}"
@@ -1590,7 +1669,7 @@ mod cross_file {
     /// so it must bring the module's implementations into scope
     #[test]
     fn a_from_import_makes_an_implementation_applicable() {
-        let db = project_db(&[
+        let project = project_db(&[
             (
                 "/iface.by",
                 "abstract class A:\n    abstract def f(self) -> int: ...\n\nclass B:\n    a: int = 3\n",
@@ -1604,7 +1683,7 @@ mod cross_file {
                 "from adapters import A\nfrom iface import B\n\ndef takes_a(x: A) -> int:\n    return x.f()\n\nb = B()\ntakes_a(b)\n",
             ),
         ]);
-        let out = transpile_file(&db, "/main.by", &Config::test_default());
+        let out = transpile_file(&project, "/main.by", &Config::test_default());
         assert!(
             out.contains("from adapters import _by_impl__A__B"),
             "witness import should be emitted, got:\n{out}"
@@ -1619,7 +1698,7 @@ mod cross_file {
     /// nothing to wrap — the checker reports the assignment instead
     #[test]
     fn implementation_without_the_import_wraps_nothing() {
-        let db = project_db(&[
+        let project = project_db(&[
             (
                 "/iface.by",
                 "abstract class A:\n    abstract def f(self) -> int: ...\n\nclass B:\n    a: int = 3\n",
@@ -1633,7 +1712,7 @@ mod cross_file {
                 "from iface import A, B\n\ndef takes_a(a: A) -> int:\n    return a.f()\n\nb = B()\ntakes_a(b)\n",
             ),
         ]);
-        let out = transpile_file(&db, "/main.by", &Config::test_default());
+        let out = transpile_file(&project, "/main.by", &Config::test_default());
         assert!(out.contains("takes_a(b)"), "got:\n{out}");
         assert!(!out.contains("__by_impl__"), "got:\n{out}");
     }
@@ -1645,10 +1724,11 @@ mod cross_file {
     #[test]
     fn line_map_points_runtime_line_to_by_source() {
         let src = "from collections.abc import Iterator\n\nx: int & str\n\ndef boom() -> int:\n    return 1 // 0\n";
-        let db = project_db(&[("/m.by", src)]);
-        let file = system_path_to_file(&db, "/m.by").expect("file not in db");
+        let project = project_db(&[("/m.by", src)]);
+        let file = system_path_to_file(project.db(), "/m.by").expect("file not in db");
         let (out, map) =
-            transpile_typed_with_map(&db, file, &Config::test_default()).expect("transpile failed");
+            transpile_typed_with_map(project.db(), file, &Config::test_default(), None)
+                .expect("transpile failed");
 
         let out_idx = out
             .lines()
diff --git a/crates/by_transforms/src/transforms/context_sensitive.rs b/crates/by_transforms/src/transforms/context_sensitive.rs
index cdb9507cf2..6ddd8c402b 100644
--- a/crates/by_transforms/src/transforms/context_sensitive.rs
+++ b/crates/by_transforms/src/transforms/context_sensitive.rs
@@ -86,7 +86,7 @@ mod tests {
     fn mapped_by_line(source: &str, needle: &str) -> Option<u32> {
         let (db, file) = make_in_memory_db(source);
         let (output, line_map) =
-            transpile_typed_with_map(&db, file, &Config::test_default()).unwrap();
+            transpile_typed_with_map(&db, file, &Config::test_default(), None).unwrap();
         let index = output
             .lines()
             .position(|line| line.trim() == needle)
diff --git a/crates/by_transforms/src/transforms/frameworks.rs b/crates/by_transforms/src/transforms/frameworks.rs
index 0fa15326c4..1b9a7b87e6 100644
--- a/crates/by_transforms/src/transforms/frameworks.rs
+++ b/crates/by_transforms/src/transforms/frameworks.rs
@@ -137,7 +137,7 @@ mod tests {
 
     fn transpile_result(db: &TestDb, path: &str) -> Result<String, String> {
         let file = system_path_to_file(db, path).expect("file not in db");
-        transpile_typed(db, file, &Config::test_default()).map_err(|err| err.to_string())
+        transpile_typed(db, file, &Config::test_default(), None).map_err(|err| err.to_string())
     }
 
     /// a project db with a mock django package in site-packages (`Model` must
@@ -248,7 +248,7 @@ mod tests {
             soundness: crate::config::SoundnessPositions::all(),
             ..Config::default()
         };
-        let out = transpile_typed(&db, file, &config).expect("model should transpile");
+        let out = transpile_typed(&db, file, &config, None).expect("model should transpile");
         assert!(
             out.contains("class User(DeclarativeBase):"),
             "class structure should survive, got:\n{out}"
@@ -316,7 +316,7 @@ mod tests {
             soundness: crate::config::SoundnessPositions::all(),
             ..Config::default()
         };
-        let out = transpile_typed(&db, file, &config).expect("model should transpile");
+        let out = transpile_typed(&db, file, &config, None).expect("model should transpile");
         assert!(
             out.contains("class Author(models.Model):"),
             "class structure should survive, got:\n{out}"
@@ -424,7 +424,8 @@ mod tests {
             min_version: ruff_python_ast::PythonVersion::PY313,
             ..Config::test_default()
         };
-        let out = transpile_typed(&db, file, &config).expect("generic model should transpile");
+        let out =
+            transpile_typed(&db, file, &config, None).expect("generic model should transpile");
         assert!(
             !out.contains("@generic"),
             "a model class must never be wrapped with `@generic`, got:\n{out}"
@@ -462,7 +463,7 @@ mod tests {
             soundness: crate::config::SoundnessPositions::all(),
             ..Config::default()
         };
-        let out = transpile_typed(&db, file, &config).expect("model should transpile");
+        let out = transpile_typed(&db, file, &config, None).expect("model should transpile");
         assert!(
             out.contains("class User(BaseModel):"),
             "class structure should survive, got:\n{out}"
diff --git a/crates/by_transforms/src/transforms/kw_subscript.rs b/crates/by_transforms/src/transforms/kw_subscript.rs
index d8f121d010..db87794a56 100644
--- a/crates/by_transforms/src/transforms/kw_subscript.rs
+++ b/crates/by_transforms/src/transforms/kw_subscript.rs
@@ -393,7 +393,7 @@ mod tests {
                 .expect("write file failed");
             db.init_program().expect("program init failed");
             let file = system_path_to_file(&db, "/proj/main.by").expect("file not in db");
-            transpile_typed(&db, file, &Config::test_default()).expect("transpile failed")
+            transpile_typed(&db, file, &Config::test_default(), None).expect("transpile failed")
         }
 
         #[test]
diff --git a/crates/ty/src/by_commands.rs b/crates/ty/src/by_commands.rs
index ce1d072f5d..fa0bbacba1 100644
--- a/crates/ty/src/by_commands.rs
+++ b/crates/ty/src/by_commands.rs
@@ -11,7 +11,7 @@ use ruff_db::diagnostic::{
     Span,
 };
 use ruff_db::files::system_path_to_file;
-use ruff_db::system::{OsSystem, SystemPath};
+use ruff_db::system::{OsSystem, SystemPath, SystemPathBuf};
 use ty_project::{Db, ProjectDatabase, ProjectMetadata};
 use walkdir::WalkDir;
 
@@ -123,7 +123,7 @@ pub(crate) fn cmd_run(
         return Ok(ExitStatus::Failure);
     }
 
-    let (db, handles) = build_project_db(&cwd, &files)?;
+    let (db, handles, rebuilder) = build_project_db(&cwd, &files)?;
 
     // an explicit module always wins; otherwise the project's configured entry
     // point stands in for it. resolving before the (much slower) check means a
@@ -147,6 +147,7 @@ pub(crate) fn cmd_run(
         &handles,
         &config,
         CheckGate::AllErrors,
+        &rebuilder,
         |bpy, src, line_map| {
             let rel = bpy.strip_prefix(&cwd).unwrap_or(bpy);
             let py = tmp.path().join(rel).with_extension("py");
@@ -218,12 +219,13 @@ pub(crate) fn cmd_build(min_version: &str, lowering: &LoweringArgs) -> anyhow::R
         return Ok(ExitStatus::Success);
     }
 
-    let (db, handles) = build_project_db(&cwd, &files)?;
+    let (db, handles, rebuilder) = build_project_db(&cwd, &files)?;
     if !render_check_and_transpile(
         &db,
         &handles,
         &config,
         CheckGate::ParseErrorsOnly,
+        &rebuilder,
         |bpy, src, _line_map| {
             let py = out
                 .join(bpy.strip_prefix(&cwd).unwrap())
@@ -313,6 +315,11 @@ pub(crate) fn cmd_transpile(
         let system = OsSystem::new(project_root);
         let project_metadata = ProjectMetadata::discover(project_root, &system)
             .with_context(|| format!("failed to discover project at {project_root}"))?;
+        let rebuilder = Rebuilder {
+            metadata: project_metadata.clone(),
+            root: project_root.to_path_buf(),
+            included: vec![sys_path.to_path_buf()],
+        };
         let mut db = ProjectDatabase::use_defaults(project_metadata, system);
         let file = system_path_to_file(&db, sys_path)
             .with_context(|| format!("file not found in db: {sys_path}"))?;
@@ -333,7 +340,8 @@ pub(crate) fn cmd_transpile(
             return Ok(ExitStatus::Failure);
         }
 
-        match by_transforms::transpile_typed(&db, file, &config) {
+        let rebuild = || Some(rebuilder.rebuild());
+        match by_transforms::transpile_typed(&db, file, &config, Some(&rebuild)) {
             Ok(out) => {
                 if !diagnostics.is_empty() {
                     render_diagnostics(&db, &diagnostics)?;
@@ -428,12 +436,13 @@ fn forward_dir(dir: &Path, config: &Config) -> anyhow::Result<ExitStatus> {
         return Ok(ExitStatus::Success);
     }
 
-    let (db, handles) = build_project_db(dir, &files)?;
+    let (db, handles, rebuilder) = build_project_db(dir, &files)?;
     let ok = render_check_and_transpile(
         &db,
         &handles,
         config,
         CheckGate::ParseErrorsOnly,
+        &rebuilder,
         |bpy, src, _line_map| {
             let py = bpy.with_extension("py");
             fs::write(&py, src).with_context(|| format!("{}", py.display()))?;
@@ -613,13 +622,42 @@ fn bpy_files(root: &Path) -> Vec<PathBuf> {
         .collect()
 }
 
+/// Everything needed to build a project db a second time.
+///
+/// The transpiler asks for one when a pre-pass rewrites the source it hands to
+/// phase 0: it then serves the rewritten file out of that db, keeping the
+/// project's metadata, search paths and sibling files. The rebuilt db must be
+/// independent of the one this command uses — see
+/// [`by_transforms::RebuildProject`].
+struct Rebuilder {
+    metadata: ProjectMetadata,
+    root: SystemPathBuf,
+    included: Vec<SystemPathBuf>,
+}
+
+impl Rebuilder {
+    fn rebuild(&self) -> Box<dyn ty_python_semantic::Db> {
+        let mut db =
+            ProjectDatabase::use_defaults(self.metadata.clone(), OsSystem::new(&self.root));
+        db.project()
+            .set_included_paths(&mut db, self.included.clone());
+        Box::new(db)
+    }
+}
+
+/// A project db, the `(source_path, File)` pairs for the `.by` files it was
+/// built for, and the means to build the same project again.
+type ProjectBuild = (
+    ProjectDatabase,
+    Vec<(PathBuf, ruff_db::files::File)>,
+    Rebuilder,
+);
+
 /// Build a project db rooted at `cwd` with every `.by` file under it set as
 /// an included path, returning the db alongside `(source_path, File)` pairs
-/// in the same order as the input slice.
-fn build_project_db(
-    cwd: &Path,
-    files: &[PathBuf],
-) -> anyhow::Result<(ProjectDatabase, Vec<(PathBuf, ruff_db::files::File)>)> {
+/// in the same order as the input slice, and the means to build the same
+/// project again.
+fn build_project_db(cwd: &Path, files: &[PathBuf]) -> anyhow::Result<ProjectBuild> {
     // the project root must be canonicalized the same way the included files
     // are (below) so it stays a path *prefix* of them: otherwise a file's
     // search path isn't recognized as first-party and boundary diagnostics
@@ -632,6 +670,7 @@ fn build_project_db(
     let system = OsSystem::new(sys_cwd);
     let project_metadata = ProjectMetadata::discover(sys_cwd, &system)
         .with_context(|| format!("failed to discover project at {sys_cwd}"))?;
+    let metadata = project_metadata.clone();
     let mut db = ProjectDatabase::use_defaults(project_metadata, system);
 
     let mut handles = Vec::with_capacity(files.len());
@@ -645,8 +684,13 @@ fn build_project_db(
             .with_context(|| format!("file not found in db: {sys_path}"))?;
         handles.push((bpy.clone(), f));
     }
+    let rebuilder = Rebuilder {
+        metadata,
+        root: sys_cwd.to_path_buf(),
+        included: included.clone(),
+    };
     db.project().set_included_paths(&mut db, included);
-    Ok((db, handles))
+    Ok((db, handles, rebuilder))
 }
 
 /// How much of the check outcome blocks emitting output.
@@ -671,6 +715,7 @@ fn render_check_and_transpile(
     handles: &[(PathBuf, ruff_db::files::File)],
     config: &Config,
     gate: CheckGate,
+    rebuilder: &Rebuilder,
     mut consume: impl FnMut(&Path, &str, &[Option<u32>]) -> anyhow::Result<()>,
 ) -> anyhow::Result<bool> {
     let mut all_diagnostics: Vec<Diagnostic> = Vec::new();
@@ -696,8 +741,9 @@ fn render_check_and_transpile(
         return Ok(false);
     }
 
+    let rebuild = || Some(rebuilder.rebuild());
     for (bpy, file) in handles {
-        match by_transforms::transpile_typed_with_map(db, *file, config) {
+        match by_transforms::transpile_typed_with_map(db, *file, config, Some(&rebuild)) {
             Ok((out, line_map)) => consume(bpy, &out, &line_map)?,
             Err(e) => {
                 all_diagnostics.push(transpile_bug_diagnostic(*file, &e));
diff --git a/docs/basedpython/development/how-transpilation-works.md b/docs/basedpython/development/how-transpilation-works.md
index 5052448914..81fffb4fcf 100644
--- a/docs/basedpython/development/how-transpilation-works.md
+++ b/docs/basedpython/development/how-transpilation-works.md
@@ -13,7 +13,9 @@ source (.by)
   │     ├─ strip use-site variance keywords (`out`/`in`) up front
   │     ├─ parse via ruff_python_parser (the unified parser accepts `.by` syntax)
   │     ├─ build a SemanticModel — the project db when available (cross-module
-  │     │  type info), else a single-file in-memory db
+  │     │  type info), else a single-file in-memory db. a pre-pass that rewrote
+  │     │  the source doesn't cost the project: the db is rebuilt over the
+  │     │  rewritten text (see "the phase-0 database" below)
   │     ├─ run AstPasses: mutate the AST in place (coalesce, cast, typeof,
   │     │  sentinel, mutable-defaults, …)
   │     ├─ run TypeAwarePasses: read the SemanticModel and emit text edits
@@ -51,10 +53,31 @@ entry points in `crates/by_transforms/src/lib.rs`:
 
 - `transpile(source, config) -> Result<String, String>` — single-file (stdin,
     tests); type-aware passes see only this file
-- `transpile_typed(db, file, config)` — uses an existing project db so type-aware
-    passes resolve cross-module types (the CLI path for `by transpile`/`build`/`run`)
-- `transpile_typed_with_map(db, file, config)` — also returns a line table for
-    traceback rewriting and diagnostic mapping
+- `transpile_typed(db, file, config, rebuild)` — uses an existing project db so
+    type-aware passes resolve cross-module types (the CLI path for
+    `by transpile`, `by build` and `by run`)
+- `transpile_typed_with_map(db, file, config, rebuild)` — also returns a line
+    table for traceback rewriting and diagnostic mapping
+
+## the phase-0 database
+
+three pre-passes run before phase 0 and can rewrite the source: erased-union
+reification, context-sensitive name qualification, and enum lowering. phase 0
+re-parses its input and binds `inferred_type` to those exact node identities, so
+its database has to hold the *rewritten* text, not the project file's
+
+that would leave phase 0 with a single-file in-memory db — no search paths, no
+sibling modules — and every `TypeAwarePass` silently declining to lower, so an
+enum declared anywhere in a file would break a lookup elsewhere in it. instead
+the caller supplies a `RebuildProject`: a way to build a second database over the
+same project, into which the rewritten source is served for this one file via
+`File::source_text_override`. the project's metadata, search paths and sibling
+files stay; only the file being transpiled reads differently
+
+the rebuilt database must be a *new* one rather than a clone — salsa handles
+cloned from one database share storage, so the override would be visible through
+the caller's own db. a caller with no project (a bare unit test) passes `None`
+and gets the single-file db: correct, just blind past the file
 
 ## passes