README.md in code_ownership-1.28.0 vs README.md in code_ownership-1.28.2

@@ -1,16 +1,19 @@
 # CodeOwnership
-This gem helps engineering teams declare ownership of code.
 
-Check out `lib/code_ownership.rb` to see the public API.
+This gem helps engineering teams declare ownership of code. This gem works best in large, usually monolithic code bases where many teams work together.
 
-Check out `code_ownership_spec.rb` to see examples of how code ownership is used.
+Check out [`lib/code_ownership.rb`](https://github.com/rubyatscale/code_ownership/blob/main/lib/code_ownership.rb) to see the public API.
 
+Check out [`code_ownership_spec.rb`](https://github.com/rubyatscale/code_ownership/blob/main/spec/lib/code_ownership_spec.rb) to see examples of how code ownership is used.
+
 There is also a [companion VSCode Extension]([url](https://github.com/rubyatscale/code-ownership-vscode)) for this gem. Just search `Gusto.code-ownership-vscode` in the VSCode Extension Marketplace.
 
 ## Usage: Declaring Ownership
+
 There are three ways to declare code ownership using this gem.
+
 ### Package-Based Ownership
 Package based ownership integrates [`packwerk`](https://github.com/Shopify/packwerk) and has ownership defined per package. To define that all files within a package are owned by one team, configure your `package.yml` like this:
 ```yml
 enforce_dependency: true
 enforce_privacy: true
@@ -29,10 +32,33 @@
 ### File-Annotation Based Ownership
 File annotations are a last resort if there is no clear home for your code. File annotations go at the top of your file, and look like this:
 ```ruby
 # @team MyTeam
 ```
+
+### Javascript Package Ownership
+Javascript package based ownership allows you to specify an owenrship key in a `package.json`. To use this, configure your `package.json` like this:
+
+```json
+{
+  // other keys
+  "metadata": {
+    "owner": "My Team"
+  }
+  // other keys
+}
+```
+
+You can also tell `code_ownership` where to find JS packages in the configuration, like this:
+```yml
+js_package_paths:
+  - frontend/javascripts/packages/*
+  - frontend/other_location_for_packages/*
+```
+
+This defaults `**/`, which makes it look for `package.json` files across your application.
+
 ## Usage: Reading CodeOwnership
 ### `for_file`
 `CodeOwnership.for_file`, given a relative path to a file returns a `CodeTeams::Team` if there is a team that owns the file, `nil` otherwise.
 
 ```ruby
@@ -69,10 +95,12 @@
 ## Usage: Generating a `CODEOWNERS` file
 
 A `CODEOWNERS` file defines who owns specific files or paths in a repository. When you run `bin/codeownership validate`, a `.github/CODEOWNERS` file will automatically be generated and updated.
 
 ## Proper Configuration & Validation
+
 CodeOwnership comes with a validation function to ensure the following things are true:
+
 1) Only one mechanism is defining file ownership. That is -- you can't have a file annotation on a file owned via package-based or glob-based ownership. This helps make ownership behavior more clear by avoiding concerns about precedence.
 2) All teams referenced as an owner for any file or package is a valid team (i.e. it's in the list of `CodeTeams.all`).
 3) All files have ownership. You can specify in `unowned_globs` to represent a TODO list of files to add ownership to.
 3) The `.github/CODEOWNERS` file is up to date. This is automatically corrected and staged unless specified otherwise with `bin/codeownership validate --skip-autocorrect --skip-stage`. You can turn this validation off by setting `skip_codeowners_validation: true` in `code_ownership.yml`.