docs: address reviewer feedback on migration guide and resources doc

migration.md: added note that static URIs with Context-only handlers
now error at decoration time. The pattern was previously silently
unreachable (the resource registered but could never be read); now
it surfaces early. Duplicate-variable-names rejection was already
covered in the malformed-templates paragraph.

resources.md: clarified that the .. check is depth-based (rejects
values that would escape the starting directory, so a/../b passes).
Changed template reference table intro from 'what the SDK supports'
to 'the most common patterns' since the table intentionally omits
the rarely-used fragment and path-param operators.

test_uri_template.py: corrected the stray-} test comment. RFC 6570
section 2.1 strictly excludes } from literals; we accept it for
TypeScript SDK parity, not because the RFC is lenient.

Author: maxisbey

docs/migration.md

@@ -585,6 +585,14 @@ duplicate variable names, and unsupported syntax now raise
 `InvalidUriTemplate` when the decorator runs, rather than silently
 misbehaving at match time.
 
+**Static URIs with Context-only handlers now error.** A non-template
+URI paired with a handler that takes only a `Context` parameter
+previously registered but was silently unreachable (the resource
+could never be read). This now raises `ValueError` at decoration time.
+Context injection for static resources is planned; until then, use a
+template with at least one variable or access context through other
+means.
+
 See [Resources](server/resources.md) for the full template syntax,
 security configuration, and filesystem safety utilities.
 

docs/server/resources.md

@@ -118,7 +118,7 @@ def walk_tree(path: list[str]) -> dict:
 ### Template reference
 
 The template syntax follows [RFC 6570](https://datatracker.ietf.org/doc/html/rfc6570).
-Here's what the SDK supports:
+The most common patterns:
 
 | Pattern      | Example input         | You get                 |
 |--------------|-----------------------|-------------------------|
@@ -141,7 +141,7 @@ or database operations, a hostile client can try path traversal
 
 Before your handler runs, the SDK rejects any parameter that:
 
-- contains `..` as a path component
+- would escape its starting directory via `..` components
 - looks like an absolute path (`/etc/passwd`, `C:\Windows`)
 
 The `..` check is component-based, not a substring scan. Values like
@@ -211,7 +211,7 @@ The configurable checks:
 
 | Setting                 | Default | What it does                        |
 |-------------------------|---------|-------------------------------------|
-| `reject_path_traversal` | `True`  | Rejects `..` as a path component    |
+| `reject_path_traversal` | `True`  | Rejects `..` sequences that escape the starting directory |
 | `reject_absolute_paths` | `True`  | Rejects `/foo`, `C:\foo`, UNC paths |
 | `exempt_params`         | empty   | Parameter names to skip checks for  |
 

tests/shared/test_uri_template.py

@@ -263,8 +263,10 @@ def test_parse_rejects_unclosed_brace(template: str, position: int):
     ["}}", "}", "a}b", "{a}}{b}"],
 )
 def test_parse_treats_stray_close_brace_as_literal(template: str):
-    # RFC 6570 is lenient about } outside expressions; most implementations
-    # (including the TypeScript SDK) treat it as a literal rather than erroring.
+    # RFC 6570 §2.1 strictly excludes } from literals, but we accept it
+    # for TypeScript SDK parity. A stray } almost always indicates a
+    # typo; rejecting would be more helpful but would also break
+    # cross-SDK behavior.
     tmpl = UriTemplate.parse(template)
     assert str(tmpl) == template