modern-python-guidance 0.3.0__tar.gz → 0.3.2__tar.gz

{modern_python_guidance-0.3.0 → modern_python_guidance-0.3.2}/CHANGELOG.md

@@ -2,8 +2,57 @@
 
 All notable changes to this project will be documented in this file.
 
+## [0.3.2] — 2026-05-29
+
+### Added
+
+- `deferred-annotations` guide (PEP 649): drop unnecessary `from __future__ import annotations` on Python 3.14+ projects where annotations are lazily evaluated by default (closes #28)
+- `template-strings` guide (PEP 750): use t-strings with processing functions for safe SQL/HTML parameterization instead of f-string interpolation (closes #28)
+- Guide count: 39 → 41. Layer 1 coverage: 16 → 18
+
+### Fixed
+
+- `setup_mcp` now catches `OSError` from `subprocess.run`, matching `uninstall_mcp` behavior — an unexecutable `claude` binary produces a clean error message instead of a traceback (closes #65)
+- MCP `retrieve_guides` schema `maxItems` and runtime guard updated from 39 to 41 to allow retrieval of all guides
+
+## [0.3.1] — 2026-05-29
+
+### Added
+
+- `mpg uninstall` command: reverses `mpg setup` by deregistering the MCP server and removing the Agent Skills symlink in one command (closes #63)
+- CLI flags: `--mcp-only`, `--skills-only`, `--project-dir`, `--dry-run` (no `--scope`; uninstall clears every scope `setup` can write to)
+- Per-scope MCP deregistration (`claude mcp remove -s local` and `-s user`): a live probe showed `claude mcp remove` without a scope removes nothing when the server is registered in multiple scopes, so uninstall enumerates scopes explicitly to avoid leaving residue
+- Symlink-only removal safety: only the symlink mpg created is removed (never its target), a non-symlink entity at the link path is refused, dangling symlinks are removed, and the parent `.claude/skills/` directory is preserved
+- 26 new tests (V-015 through V-031)
+
+### Changed
+
+- Extracted shared `_skills_link_path` helper in `setup_cmd` so `setup` and `uninstall` resolve the Skills symlink location identically (no drift)
+
 ## [0.3.0] — 2026-05-28
 
+### Added
+
+- `mpg setup` command: one-command MCP server registration + Agent Skills symlink creation. Replaces 3-4 manual steps with `pip install modern-python-guidance && mpg setup` (closes #60)
+- CLI flags: `--mcp-only`, `--skills-only`, `--scope {user,local}`, `--project-dir`, `--dry-run`
+- Project root auto-detection (`.claude/` → `.git/` → `pyproject.toml` upward search) for correct Skills symlink placement from subdirectories
+- Idempotent operation: re-running `mpg setup` skips already-correct state, replaces stale/broken symlinks, errors on non-symlink blockers
+- Partial success handling: MCP and Skills run independently; one failure does not block the other
+- 33 new tests for setup command (V-001 through V-014 verification points)
+
+### Changed
+
+- README Quick Start: reduced from 3 code blocks to 2 lines (`pip install` + `mpg setup`). Manual setup moved to collapsible `<details>` section
+
+## [0.2.3] — 2026-05-28
+
+### Fixed
+
+- `fastapi-typed-state` guide: added missing Version Notes section (closes #13)
+- `fastapi-typed-state` and `fastapi-lifespan` guides: corrected minimum version from FastAPI >= 0.93.0 to >= 0.94.0 (lifespan state dict requires Starlette >= 0.26.0, which FastAPI 0.93.0 excludes)
+
+## [0.2.2] — 2026-05-28
+
 ### Changed
 
 - Search response (MCP + CLI) now includes `tags`, `python`, `frequency`, and `snippet` fields for richer agent decision-making without requiring a follow-up retrieve call
@@ -81,7 +130,11 @@ Initial release.
 - Strict YAML-subset frontmatter parser (no PyYAML dependency)
 - GitHub Actions CI (pytest + ruff on Python 3.11, 3.12, 3.13)
 
+[0.3.2]: https://github.com/yottayoshida/modern-python-guidance/releases/tag/v0.3.2
+[0.3.1]: https://github.com/yottayoshida/modern-python-guidance/releases/tag/v0.3.1
 [0.3.0]: https://github.com/yottayoshida/modern-python-guidance/releases/tag/v0.3.0
+[0.2.3]: https://github.com/yottayoshida/modern-python-guidance/releases/tag/v0.2.3
+[0.2.2]: https://github.com/yottayoshida/modern-python-guidance/releases/tag/v0.2.2
 [0.2.1]: https://github.com/yottayoshida/modern-python-guidance/releases/tag/v0.2.1
 [0.2.0]: https://github.com/yottayoshida/modern-python-guidance/releases/tag/v0.2.0
 [0.1.2]: https://github.com/yottayoshida/modern-python-guidance/releases/tag/v0.1.2

{modern_python_guidance-0.3.0 → modern_python_guidance-0.3.2}/CONTRIBUTING.md

@@ -15,7 +15,7 @@ src/modern_python_guidance/
 
 skills/modern-python-guidance/
 ├── SKILL.md            # Agent Skills plugin entry point
-└── guides/             # 39 guide files by category
+└── guides/             # 41 guide files by category
 ```
 
 See [docs/design.md](docs/design.md) for the full design document.

{modern_python_guidance-0.3.0 → modern_python_guidance-0.3.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: modern-python-guidance
-Version: 0.3.0
+Version: 0.3.2
 Summary: Version-aware BAD/GOOD pattern guides that help AI coding agents generate modern Python
 Project-URL: Homepage, https://github.com/yottayoshida/modern-python-guidance
 Project-URL: Repository, https://github.com/yottayoshida/modern-python-guidance
@@ -36,12 +36,12 @@ Description-Content-Type: text/markdown
 [![Python](https://img.shields.io/pypi/pyversions/modern-python-guidance.svg)](https://pypi.org/project/modern-python-guidance/)
 [![License](https://img.shields.io/github/license/yottayoshida/modern-python-guidance.svg)](LICENSE)
 
-Stop your AI from writing `typing.List`, `@validator`, and `setup.py`. 39 version-aware BAD/GOOD pattern guides that teach AI coding agents to write modern Python — delivered via MCP, CLI, or Agent Skills.
+Stop your AI from writing `typing.List`, `@validator`, and `setup.py`. 41 version-aware BAD/GOOD pattern guides that teach AI coding agents to write modern Python — delivered via MCP, CLI, or Agent Skills.
 
 ## Highlights
 
 - **Measurable impact**: +14.7pp overall improvement in A/B benchmark via Agent Skills (38 scored items, [details](docs/benchmark-evaluation.md)). Largest variant (FastAPI, 32 items): Control 60.4% → Treatment 82.3%
-- **39 guides** across stdlib, Pydantic, FastAPI, Django, SQLAlchemy, pytest, and toolchain
+- **41 guides** across stdlib, Pydantic, FastAPI, Django, SQLAlchemy, pytest, and toolchain
 - **Version-aware**: auto-detects your project's Python version and filters guides accordingly
 - **3 delivery methods**: MCP server, CLI, Agent Skills plugin
 - **Not Ruff**: Ruff auto-fixes syntax (`List` → `list`). mpg guides design decisions that Ruff can't touch — `TaskGroup` over `gather`, Pydantic V2 migration, SQLAlchemy 2.0 style
@@ -50,15 +50,29 @@ Stop your AI from writing `typing.List`, `@validator`, and `setup.py`. 39 versio
 
 ## Quick start
 
-### MCP (for AI coding agents)
+### Claude Code (recommended)
 
-Install, then register the MCP server with your agent:
+```bash
+pip install modern-python-guidance
+mpg setup
+```
+
+This registers the MCP server and links Agent Skills in one command. Start a new Claude Code session afterwards — newly registered MCP servers and skills take effect on the next launch.
+
+### CLI
 
 ```bash
 pip install modern-python-guidance
+mpg search "pydantic validator"
+mpg retrieve pydantic-v2-validators
 ```
 
-**Claude Code:**
+`mpg` is the short alias for `modern-python-guidance`. Both work.
+
+<details>
+<summary>Manual setup / other agents</summary>
+
+**MCP registration (Claude Code):**
 ```bash
 claude mcp add mpg -- mpg mcp
 ```
@@ -75,29 +89,36 @@ claude mcp add mpg -- mpg mcp
 }
 ```
 
-Your agent gets access to `search_guides`, `retrieve_guides`, `list_guides`, and `detect_python_version`.
-
-### CLI
-
+**Agent Skills symlink (Claude Code):**
 ```bash
-pip install modern-python-guidance
-
-# Search for a pattern
-mpg search "pydantic validator"
-
-# Get the full guide
-mpg retrieve pydantic-v2-validators
+mpg setup --skills-only
 ```
 
-### Agent Skills (Claude Code plugin)
+**`mpg setup` flags:**
+| Flag | Purpose |
+|------|---------|
+| `--mcp-only` | MCP registration only |
+| `--skills-only` | Agent Skills symlink only |
+| `--scope {user,local}` | MCP scope (default: user) |
+| `--project-dir PATH` | Target project for Skills symlink |
+| `--dry-run` | Show what would be done |
 
+**Uninstall** — reverse `mpg setup` (deregister the MCP server and unlink Agent Skills):
 ```bash
-# Symlink into your project
-SKILL_DIR=$(python -c "from pathlib import Path; import modern_python_guidance; print(Path(modern_python_guidance.__file__).parent / 'skills' / 'modern-python-guidance')")
-ln -s "$SKILL_DIR" your-project/.claude/skills/modern-python-guidance
+mpg uninstall            # remove both
+mpg uninstall --dry-run  # preview what would be removed
 ```
 
-`mpg` is the short alias for `modern-python-guidance`. Both work.
+| Flag | Purpose |
+|------|---------|
+| `--mcp-only` | MCP deregistration only |
+| `--skills-only` | Agent Skills unlink only |
+| `--project-dir PATH` | Target project for the Skills symlink |
+| `--dry-run` | Show what would be done |
+
+`mpg uninstall` clears the MCP registration from every scope `setup` can write to (user and local), removes only the symlink mpg created (never its target or other skills), and is idempotent — running it on an already-clean state is a harmless no-op.
+
+</details>
 
 ## CLI usage
 
@@ -123,15 +144,15 @@ mpg search "typing" --format json | jq '.[0].id'
 
 ## Guide coverage
 
-39 guides across 3 layers:
+41 guides across 3 layers:
 
 | Layer | Categories | Count | Examples |
 |-------|-----------|-------|---------|
-| **1 — stdlib** | typing, async, stdlib, data-structures | 16 | `list` over `List`, `match`/`case`, `TaskGroup` |
+| **1 — stdlib** | typing, async, stdlib, data-structures | 18 | `list` over `List`, `match`/`case`, `TaskGroup`, deferred annotations, t-strings |
 | **2 — frameworks** | pydantic, fastapi, httpx, django, sqlalchemy, pytest | 18 | Pydantic V2 migration, SQLAlchemy 2.0 style, `Annotated[Depends]` |
 | **3 — toolchain** | toolchain | 5 | `uv` over `pip`, `ruff` over flake8, `pickle` avoidance |
 
-Run `mpg list` to see all 39 guides, or [browse them on GitHub](skills/modern-python-guidance/guides/).
+Run `mpg list` to see all 41 guides, or [browse them on GitHub](skills/modern-python-guidance/guides/).
 
 ## Version-aware filtering
 

{modern_python_guidance-0.3.0 → modern_python_guidance-0.3.2}/README.md

@@ -5,12 +5,12 @@
 [![Python](https://img.shields.io/pypi/pyversions/modern-python-guidance.svg)](https://pypi.org/project/modern-python-guidance/)
 [![License](https://img.shields.io/github/license/yottayoshida/modern-python-guidance.svg)](LICENSE)
 
-Stop your AI from writing `typing.List`, `@validator`, and `setup.py`. 39 version-aware BAD/GOOD pattern guides that teach AI coding agents to write modern Python — delivered via MCP, CLI, or Agent Skills.
+Stop your AI from writing `typing.List`, `@validator`, and `setup.py`. 41 version-aware BAD/GOOD pattern guides that teach AI coding agents to write modern Python — delivered via MCP, CLI, or Agent Skills.
 
 ## Highlights
 
 - **Measurable impact**: +14.7pp overall improvement in A/B benchmark via Agent Skills (38 scored items, [details](docs/benchmark-evaluation.md)). Largest variant (FastAPI, 32 items): Control 60.4% → Treatment 82.3%
-- **39 guides** across stdlib, Pydantic, FastAPI, Django, SQLAlchemy, pytest, and toolchain
+- **41 guides** across stdlib, Pydantic, FastAPI, Django, SQLAlchemy, pytest, and toolchain
 - **Version-aware**: auto-detects your project's Python version and filters guides accordingly
 - **3 delivery methods**: MCP server, CLI, Agent Skills plugin
 - **Not Ruff**: Ruff auto-fixes syntax (`List` → `list`). mpg guides design decisions that Ruff can't touch — `TaskGroup` over `gather`, Pydantic V2 migration, SQLAlchemy 2.0 style
@@ -19,15 +19,29 @@ Stop your AI from writing `typing.List`, `@validator`, and `setup.py`. 39 versio
 
 ## Quick start
 
-### MCP (for AI coding agents)
+### Claude Code (recommended)
 
-Install, then register the MCP server with your agent:
+```bash
+pip install modern-python-guidance
+mpg setup
+```
+
+This registers the MCP server and links Agent Skills in one command. Start a new Claude Code session afterwards — newly registered MCP servers and skills take effect on the next launch.
+
+### CLI
 
 ```bash
 pip install modern-python-guidance
+mpg search "pydantic validator"
+mpg retrieve pydantic-v2-validators
 ```
 
-**Claude Code:**
+`mpg` is the short alias for `modern-python-guidance`. Both work.
+
+<details>
+<summary>Manual setup / other agents</summary>
+
+**MCP registration (Claude Code):**
 ```bash
 claude mcp add mpg -- mpg mcp
 ```
@@ -44,29 +58,36 @@ claude mcp add mpg -- mpg mcp
 }
 ```
 
-Your agent gets access to `search_guides`, `retrieve_guides`, `list_guides`, and `detect_python_version`.
-
-### CLI
-
+**Agent Skills symlink (Claude Code):**
 ```bash
-pip install modern-python-guidance
-
-# Search for a pattern
-mpg search "pydantic validator"
-
-# Get the full guide
-mpg retrieve pydantic-v2-validators
+mpg setup --skills-only
 ```
 
-### Agent Skills (Claude Code plugin)
+**`mpg setup` flags:**
+| Flag | Purpose |
+|------|---------|
+| `--mcp-only` | MCP registration only |
+| `--skills-only` | Agent Skills symlink only |
+| `--scope {user,local}` | MCP scope (default: user) |
+| `--project-dir PATH` | Target project for Skills symlink |
+| `--dry-run` | Show what would be done |
 
+**Uninstall** — reverse `mpg setup` (deregister the MCP server and unlink Agent Skills):
 ```bash
-# Symlink into your project
-SKILL_DIR=$(python -c "from pathlib import Path; import modern_python_guidance; print(Path(modern_python_guidance.__file__).parent / 'skills' / 'modern-python-guidance')")
-ln -s "$SKILL_DIR" your-project/.claude/skills/modern-python-guidance
+mpg uninstall            # remove both
+mpg uninstall --dry-run  # preview what would be removed
 ```
 
-`mpg` is the short alias for `modern-python-guidance`. Both work.
+| Flag | Purpose |
+|------|---------|
+| `--mcp-only` | MCP deregistration only |
+| `--skills-only` | Agent Skills unlink only |
+| `--project-dir PATH` | Target project for the Skills symlink |
+| `--dry-run` | Show what would be done |
+
+`mpg uninstall` clears the MCP registration from every scope `setup` can write to (user and local), removes only the symlink mpg created (never its target or other skills), and is idempotent — running it on an already-clean state is a harmless no-op.
+
+</details>
 
 ## CLI usage
 
@@ -92,15 +113,15 @@ mpg search "typing" --format json | jq '.[0].id'
 
 ## Guide coverage
 
-39 guides across 3 layers:
+41 guides across 3 layers:
 
 | Layer | Categories | Count | Examples |
 |-------|-----------|-------|---------|
-| **1 — stdlib** | typing, async, stdlib, data-structures | 16 | `list` over `List`, `match`/`case`, `TaskGroup` |
+| **1 — stdlib** | typing, async, stdlib, data-structures | 18 | `list` over `List`, `match`/`case`, `TaskGroup`, deferred annotations, t-strings |
 | **2 — frameworks** | pydantic, fastapi, httpx, django, sqlalchemy, pytest | 18 | Pydantic V2 migration, SQLAlchemy 2.0 style, `Annotated[Depends]` |
 | **3 — toolchain** | toolchain | 5 | `uv` over `pip`, `ruff` over flake8, `pickle` avoidance |
 
-Run `mpg list` to see all 39 guides, or [browse them on GitHub](skills/modern-python-guidance/guides/).
+Run `mpg list` to see all 41 guides, or [browse them on GitHub](skills/modern-python-guidance/guides/).
 
 ## Version-aware filtering
 

{modern_python_guidance-0.3.0 → modern_python_guidance-0.3.2}/docs/design.md

@@ -52,7 +52,7 @@ LLMs frequently generate outdated Python patterns: `typing.List` instead of `lis
 │  typing/ async/ stdlib/ data-structures/                │
 │  pydantic/ fastapi/ httpx/ toolchain/                   │
 │  django/ sqlalchemy/ pytest/                            │
-│  (39 guide files)                                       │
+│  (41 guide files)                                       │
 └─────────────────────────────────────────────────────────┘
 ```
 

{modern_python_guidance-0.3.0 → modern_python_guidance-0.3.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "modern-python-guidance"
-version = "0.3.0"
+version = "0.3.2"
 description = "Version-aware BAD/GOOD pattern guides that help AI coding agents generate modern Python"
 readme = "README.md"
 license = "Apache-2.0 OR MIT"

{modern_python_guidance-0.3.0 → modern_python_guidance-0.3.2}/skills/modern-python-guidance/SKILL.md

@@ -55,11 +55,11 @@ Pre-generation design patterns that Ruff cannot auto-fix. Apply these transforma
 - `subprocess.run(f"cmd {arg}", shell=True)` → `subprocess.run(["cmd", arg], check=True)`
   - Caveat: `shell=True` is valid when pipes/globs are needed; use `shlex.quote()` for user input
 
-## All 39 guides by category
+## All 41 guides by category
 
-- **typing** (6): `use-builtin-generics`, `union-syntax`, `type-parameter-syntax`, `override-decorator`, `typeis-vs-typeguard`, `paramspec-decorators`
+- **typing** (7): `use-builtin-generics`, `union-syntax`, `type-parameter-syntax`, `override-decorator`, `typeis-vs-typeguard`, `paramspec-decorators`, `deferred-annotations`
 - **async** (3): `taskgroup-over-gather`, `exception-groups`, `async-timeout-context`
-- **stdlib** (4): `datetime-utc`, `pathlib-over-os-path`, `tomllib-builtin`, `removeprefix-removesuffix`
+- **stdlib** (5): `datetime-utc`, `pathlib-over-os-path`, `tomllib-builtin`, `removeprefix-removesuffix`, `template-strings`
 - **data-structures** (3): `dict-merge-operator`, `match-case-patterns`, `dataclass-modern`
 - **pydantic** (4): `pydantic-v2-validators`, `pydantic-v2-config`, `pydantic-v2-model-api`, `pydantic-v2-serialization`
 - **fastapi** (3): `fastapi-lifespan`, `fastapi-annotated-depends`, `fastapi-typed-state`

{modern_python_guidance-0.3.0 → modern_python_guidance-0.3.2}/skills/modern-python-guidance/guides/fastapi/fastapi-lifespan.md

@@ -68,7 +68,7 @@ async def root(request: Request):
 
 ## Version Notes
 
-- Works on Python 3.9+ with FastAPI >= 0.93.0
+- Works on Python 3.9+ with FastAPI >= 0.94.0 (lifespan state dict requires Starlette >= 0.26.0)
 - `AsyncIterator` moved from `typing` to `collections.abc` in 3.9
 
 ## References

{modern_python_guidance-0.3.0 → modern_python_guidance-0.3.2}/skills/modern-python-guidance/guides/fastapi/fastapi-typed-state.md

@@ -70,6 +70,11 @@ async def root(request: Request):
 - `dataclass` or `TypedDict` documents the expected shape
 - Resource cleanup is guaranteed by the context manager
 
+## Version Notes
+
+- Lifespan state dict requires FastAPI >= 0.94.0 (Starlette >= 0.26.0)
+- `@dataclass(slots=True)` requires Python 3.10+; use plain `@dataclass` on 3.9
+
 ## References
 
 - [FastAPI Lifespan State](https://fastapi.tiangolo.com/advanced/events/#lifespan-state)

modern_python_guidance-0.3.2/skills/modern-python-guidance/guides/stdlib/template-strings.md

@@ -0,0 +1,70 @@
+---
+id: template-strings
+title: Use Template Strings (t-strings) for Structured String Processing
+category: stdlib
+layer: 1
+tags:
+  - strings
+  - templates
+  - security
+  - sql
+aliases:
+  - t-string
+  - 't"'
+  - Template
+  - string.templatelib
+python: ">=3.14"
+frequency: medium
+pep: 750
+---
+
+# Use Template Strings for Structured String Processing
+
+Python 3.14 introduces t-strings (PEP 750): a `t"..."` prefix that produces a `Template` object instead of a `str`. Pass the `Template` to a processing function that separates literal text from interpolated values, enabling safe parameterization for SQL, HTML, shell commands, and other injection-sensitive contexts.
+
+## BAD
+
+```python
+def query_user(db, user_id: str) -> dict:
+    sql = f"SELECT * FROM users WHERE id = '{user_id}'"
+    return db.execute(sql).fetchone()
+```
+
+## GOOD
+
+```python
+from string.templatelib import Interpolation
+
+def sql(template) -> tuple[str, list]:
+    parts, params = [], []
+    for item in template:
+        if isinstance(item, Interpolation):
+            parts.append("?")
+            params.append(item.value)
+        else:
+            parts.append(item)
+    return "".join(parts), params
+
+def query_user(db, user_id: str) -> dict:
+    query, params = sql(t"SELECT * FROM users WHERE id = {user_id}")
+    return db.execute(query, params).fetchone()
+```
+
+## Why
+
+- f-strings produce a final `str` with interpolated values already baked in, making it impossible to distinguish user input from literal SQL after the fact
+- t-strings produce a `Template` that preserves the structure: literal segments as strings, interpolated values as `Interpolation` objects with `value`, `expression`, `conversion`, and `format_spec` attributes
+- A processing function can then route each interpolated value through proper escaping or parameterization, preventing injection by construction
+- t-strings do NOT make strings safe by themselves -- safety comes entirely from the processing function that receives the `Template`
+
+## Version Notes
+
+- 3.14+: `t"..."` syntax and `string.templatelib` module (`Template`, `Interpolation`)
+- Pre-3.14: Use parameterized queries directly (`db.execute("SELECT ... WHERE id = ?", [user_id])`) or template engines with auto-escaping
+- For simple string formatting where injection is not a concern, f-strings remain the appropriate choice
+- `Template` objects do not render to `str` automatically -- a processing function is always required
+
+## References
+
+- [PEP 750 -- Template Strings](https://peps.python.org/pep-0750/)
+- [string.templatelib documentation](https://docs.python.org/3/library/string.templatelib.html)

modern_python_guidance-0.3.2/skills/modern-python-guidance/guides/typing/deferred-annotations.md

@@ -0,0 +1,63 @@
+---
+id: deferred-annotations
+title: 'Drop "from __future__ import annotations" on Python 3.14+'
+category: typing
+layer: 1
+tags:
+  - type-hints
+  - annotations
+  - forward-reference
+aliases:
+  - "from __future__ import annotations"
+  - "__future__.annotations"
+  - ForwardRef
+python: ">=3.14"
+frequency: high
+pep: 649
+---
+
+# Drop `from __future__ import annotations` on Python 3.14+
+
+On Python 3.14+, annotations are lazily evaluated by default (PEP 649). The `from __future__ import annotations` import is no longer needed for forward references in 3.14-only projects.
+
+## BAD
+
+```python
+from __future__ import annotations
+
+class Tree:
+    left: Tree | None = None
+    right: Tree | None = None
+
+    def children(self) -> list[Tree]:
+        return [c for c in (self.left, self.right) if c]
+```
+
+## GOOD
+
+```python
+class Tree:
+    left: Tree | None = None
+    right: Tree | None = None
+
+    def children(self) -> list[Tree]:
+        return [c for c in (self.left, self.right) if c]
+```
+
+## Why
+
+- Python 3.14 evaluates annotations lazily by default, so forward references like `Tree` inside the `Tree` class body just work
+- The future import forces all-string semantics (PEP 563), which is different from 3.14's lazy evaluation and can interact poorly with runtime annotation consumers
+- Removing the unnecessary import keeps the module cleaner and avoids the subtle behavioral difference between stringified and lazily-evaluated annotations
+
+## Version Notes
+
+- 3.14+: Annotations are lazily evaluated by default. Remove `from __future__ import annotations` in 3.14-only projects
+- Pre-3.14: The future import remains the correct way to enable string annotations for forward references
+- `from __future__ import annotations` is deprecated but NOT removed in 3.14. It still works but forces all-string semantics. Removal is not expected before Python 3.13 EOL (~2029)
+- Libraries that read annotations at runtime (`typing.get_type_hints()`, Pydantic, FastAPI, attrs) may need updates for 3.14's lazy evaluation. Verify library compatibility before removing the import in projects that depend on runtime annotation inspection
+
+## References
+
+- [PEP 649 -- Deferred Evaluation of Annotations Using Descriptors](https://peps.python.org/pep-0649/)
+- [PEP 749 -- Implementing PEP 649](https://peps.python.org/pep-0749/)

{modern_python_guidance-0.3.0 → modern_python_guidance-0.3.2}/src/modern_python_guidance/__init__.py

@@ -1,3 +1,3 @@
 """Modern Python Guidance — version-aware BAD/GOOD pattern guides for AI coding agents."""
 
-__version__ = "0.2.0"
+__version__ = "0.3.2"

{modern_python_guidance-0.3.0 → modern_python_guidance-0.3.2}/src/modern_python_guidance/cli.py

@@ -65,6 +65,32 @@ def main(argv: list[str] | None = None) -> None:
     # mcp
     subparsers.add_parser("mcp", help="Start MCP server (JSON-RPC over stdio)")
 
+    # setup
+    p_setup = subparsers.add_parser(
+        "setup", help="Register MCP server and link Agent Skills",
+    )
+    p_setup.add_argument("--mcp-only", action="store_true", help="MCP registration only")
+    p_setup.add_argument("--skills-only", action="store_true", help="Skills symlink only")
+    p_setup.add_argument(
+        "--scope", choices=["user", "local"], default="user",
+        help="MCP scope (default: user)",
+    )
+    p_setup.add_argument(
+        "--project-dir", type=Path, help="Project directory for Skills symlink",
+    )
+    p_setup.add_argument("--dry-run", action="store_true", help="Show what would be done")
+
+    # uninstall
+    p_uninstall = subparsers.add_parser(
+        "uninstall", help="Reverse 'setup': deregister MCP server and unlink Agent Skills",
+    )
+    p_uninstall.add_argument("--mcp-only", action="store_true", help="MCP deregistration only")
+    p_uninstall.add_argument("--skills-only", action="store_true", help="Skills unlink only")
+    p_uninstall.add_argument(
+        "--project-dir", type=Path, help="Project directory for Skills symlink",
+    )
+    p_uninstall.add_argument("--dry-run", action="store_true", help="Show what would be done")
+
     args = parser.parse_args(argv)
 
     if args.command is None:
@@ -86,6 +112,10 @@ def main(argv: list[str] | None = None) -> None:
             _cmd_detect_version(args)
         elif args.command == "mcp":
             _cmd_mcp()
+        elif args.command == "setup":
+            _cmd_setup(args)
+        elif args.command == "uninstall":
+            _cmd_uninstall(args)
     except BrokenPipeError:
         sys.exit(0)
 
@@ -215,3 +245,28 @@ def _cmd_mcp() -> None:
     from modern_python_guidance.mcp_server import serve
 
     serve()
+
+
+def _cmd_setup(args: argparse.Namespace) -> None:
+    from modern_python_guidance.setup_cmd import run_setup
+
+    code = run_setup(
+        scope=args.scope,
+        mcp_only=args.mcp_only,
+        skills_only=args.skills_only,
+        project_dir=args.project_dir,
+        dry_run=args.dry_run,
+    )
+    sys.exit(code)
+
+
+def _cmd_uninstall(args: argparse.Namespace) -> None:
+    from modern_python_guidance.uninstall_cmd import run_uninstall
+
+    code = run_uninstall(
+        mcp_only=args.mcp_only,
+        skills_only=args.skills_only,
+        project_dir=args.project_dir,
+        dry_run=args.dry_run,
+    )
+    sys.exit(code)

{modern_python_guidance-0.3.0 → modern_python_guidance-0.3.2}/src/modern_python_guidance/mcp_server.py

@@ -121,8 +121,8 @@ TOOLS = [
                 "guide_ids": {
                     "type": "array",
                     "items": {"type": "string"},
-                    "description": "Guide IDs to retrieve (max 39)",
-                    "maxItems": 39,
+                    "description": "Guide IDs to retrieve (max 41)",
+                    "maxItems": 41,
                 },
                 "python_version": {
                     "type": "string",
@@ -269,8 +269,8 @@ def _tool_retrieve(arguments: dict) -> dict:
     guide_ids = arguments.get("guide_ids", [])
     if not guide_ids:
         return _tool_result("guide_ids is required and must not be empty", is_error=True)
-    if len(guide_ids) > 39:
-        return _tool_result("guide_ids exceeds maximum of 39", is_error=True)
+    if len(guide_ids) > 41:
+        return _tool_result("guide_ids exceeds maximum of 41", is_error=True)
 
     pv = arguments.get("python_version")
     err = _validate_python_version(pv)