From fbb226bce18713ea2173851e289d144a996f2b50 Mon Sep 17 00:00:00 2001
From: "J.P. Krauss" <jkrauss@asymworks.com>
Date: Sat, 14 Feb 2026 06:32:07 -0800
Subject: [PATCH] feat: update README.md

---
 README.md | 25 ++++++++++++++++++++++++-
 1 file changed, 24 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 2a3a68e..ebf3b09 100644
--- a/README.md
+++ b/README.md
@@ -1,6 +1,29 @@
 # Asymworks KiCad Library
 
-## Useful Links
+## Usage
+The recommended way to use this library is with `git subtree` into an `asymworks` folder under the current project, and reference it as a Project Library from KiCad.
 
+```sh
+git remote add -f asymworks-library https://git.asymworks.com/asymworks/kicad-library.git
+git subtree add --prefix ./asymworks asymworks-library main --squash
+```
+
+Add the library to KiCad relative to the `${KIPRJMOD}` variable.
+
+> [!NOTE]
+> The Asymworks library currently has a mix of path specs for 3D models, most of which still use the legacy `${KICAD_USER_TEMPLATE_DIR}/asymworks-kicad-library` root rather than `${KIPRJMOD}/asymworks`. Manual intervention to change the path within `pcbnew` may be required for 3D models to show up correctly.
+
+The library can be modified from the local project directory, and changes committed back to the main repository, using a similar syntax.
+
+```sh
+git add ./asymworks
+git commit -m 'feat: added footprints XXXX'
+git subtree push --prefix ./asymworks asymworks-library main
+```
+
+> [!WARNING]
+> When using `git subtree` ensure that only changes within the subtree are added to a particular commit. Mixing files in a single commit between subtree and main project files may break things.
+
+## Useful Links
 [KiCad Library Conventions](https://klc.kicad.org)