[pubspec_parse] Add README usage examples #1807 (#2582) Closes #1807

diff --git a/pkgs/pubspec_parse/CHANGELOG.md b/pkgs/pubspec_parse/CHANGELOG.md
index e0116ec..c10467c 100644
--- a/pkgs/pubspec_parse/CHANGELOG.md
+++ b/pkgs/pubspec_parse/CHANGELOG.md

@@ -1,3 +1,7 @@
+## 1.6.1
+
+- Added a usage example.
+
 ## 1.6.0
 
 - Added `toJson` method to `Pubspec` to serialize the object back to a `Map`.

diff --git a/pkgs/pubspec_parse/README.md b/pkgs/pubspec_parse/README.md
index 1d04aa4..99f607b 100644
--- a/pkgs/pubspec_parse/README.md
+++ b/pkgs/pubspec_parse/README.md

@@ -7,6 +7,18 @@
 Supports parsing `pubspec.yaml` files with robust error reporting and support
 for most of the documented features.
 
+## Usage
+
+Parse a `pubspec.yaml` string with `Pubspec.parse`. Hosted and path
+dependencies come back as `HostedDependency` and `PathDependency`.
+
+`Pubspec.parse` throws a `ParsedYamlException` from `package:checked_yaml` when
+a field is invalid. Pass `lenient: true` to ignore unknown or invalid top-level
+keys.
+
+A complete example, including loading from a file, is in
+[example/example.dart](example/example.dart).
+
 ## More information
 
 Read more about the [pubspec format](https://dart.dev/tools/pub/pubspec).

diff --git a/pkgs/pubspec_parse/example/example.dart b/pkgs/pubspec_parse/example/example.dart
new file mode 100644
index 0000000..12e741b
--- /dev/null
+++ b/pkgs/pubspec_parse/example/example.dart

@@ -0,0 +1,41 @@
+// Copyright (c) 2026, the Dart project authors. Please see the AUTHORS file
+// for details. All rights reserved. Use of this source code is governed by a
+// BSD-style license that can be found in the LICENSE file.
+
+import 'dart:io';
+
+import 'package:pubspec_parse/pubspec_parse.dart';
+
+void main() {
+  const yaml = '''
+name: my_package
+version: 1.2.3
+environment:
+  sdk: ^3.8.0
+dependencies:
+  collection: ^1.19.0
+  path:
+    path: ../path
+''';
+
+  final pubspec = Pubspec.parse(yaml);
+  print(pubspec.name); // my_package
+  print(pubspec.version); // 1.2.3
+
+  final collection = pubspec.dependencies['collection'];
+  if (collection is HostedDependency) {
+    print(collection.version); // ^1.19.0
+  }
+
+  final path = pubspec.dependencies['path'];
+  if (path is PathDependency) {
+    print(path.path); // ../path
+  }
+
+  final fromFile = File('pubspec.yaml').readAsStringSync();
+  final parsedFile = Pubspec.parse(
+    fromFile,
+    sourceUrl: Uri.file('pubspec.yaml'),
+  );
+  print('${parsedFile.name} ${parsedFile.version}');
+}

diff --git a/pkgs/pubspec_parse/pubspec.yaml b/pkgs/pubspec_parse/pubspec.yaml
index cf7711d..315dcc0 100644
--- a/pkgs/pubspec_parse/pubspec.yaml
+++ b/pkgs/pubspec_parse/pubspec.yaml

@@ -1,5 +1,5 @@
 name: pubspec_parse
-version: 1.6.0
+version: 1.6.1
 description: >-
   Simple package for parsing pubspec.yaml files with a type-safe API and rich
   error reporting.