diff --git a/packages/coding-agent/README.md b/packages/coding-agent/README.md
index 5a13d289..b869dc2b 100644
--- a/packages/coding-agent/README.md
+++ b/packages/coding-agent/README.md
@@ -1010,6 +1010,12 @@ pi update  # update all non-pinned packages
 
 Use `-l` to install into project settings (`.pi/settings.json`).
 
+**Discoverability:** Published pi packages should include the `pi-package` keyword in their `package.json` for npm search:
+
+```bash
+curl -s "https://registry.npmjs.org/-/v1/search?text=keywords:pi-package" | jq '.objects[].package.name'
+```
+
 **Package filtering:** By default, packages load all resources (extensions, skills, prompts, themes). To selectively load only certain resources, use the object form in settings.json:
 
 ```json
diff --git a/packages/coding-agent/docs/extensions.md b/packages/coding-agent/docs/extensions.md
index 098004fb..82ed5d68 100644
--- a/packages/coding-agent/docs/extensions.md
+++ b/packages/coding-agent/docs/extensions.md
@@ -242,6 +242,18 @@ To include resources from another pi package, add it as a dependency with `bundl
 
 `bundledDependencies` embeds the package inside your tarball, preserving the `node_modules/` structure. Without it, npm's hoisting could move the dependency elsewhere, breaking the paths.
 
+**Discoverability:** Add the `pi-package` keyword to your `package.json` so users can find your package on npm:
+
+```json
+{
+  "name": "my-extension-pack",
+  "keywords": ["pi-package", "pi-extension", "..."],
+  ...
+}
+```
+
+Search for pi packages: `curl -s "https://registry.npmjs.org/-/v1/search?text=keywords:pi-package"`
+
 The `package.json` approach enables:
 - Multiple extensions from one package
 - Skills, prompts, and themes declared alongside extensions