diff --git a/.agents/pm/history/pm-github-q6ql.jsonl b/.agents/pm/history/pm-github-q6ql.jsonl
new file mode 100644
index 00000000..312eded2
--- /dev/null
+++ b/.agents/pm/history/pm-github-q6ql.jsonl
@@ -0,0 +1,5 @@
+{"ts":"2026-07-25T23:48:53.463Z","author":"claude","author_source":"asserted","op":"create","patch":[{"op":"add","path":"/metadata/id","value":"pm-github-q6ql"},{"op":"add","path":"/metadata/title","value":"Documented install command fails: pm install github.com/unbraind/pm-github cannot resolve an entry file"},{"op":"add","path":"/metadata/description","value":""},{"op":"add","path":"/metadata/type","value":"Issue"},{"op":"add","path":"/metadata/status","value":"open"},{"op":"add","path":"/metadata/priority","value":1},{"op":"add","path":"/metadata/tags","value":[]},{"op":"add","path":"/metadata/created_at","value":"2026-07-25T23:48:53.463Z"},{"op":"add","path":"/metadata/updated_at","value":"2026-07-25T23:48:53.463Z"},{"op":"add","path":"/metadata/author","value":"claude"}],"before_hash":"3cc22dff72be7b14824654a7a64ea62b04799939b2fee54c1b5f52ca60bf6df0","after_hash":"8e6940b8ca0afdcb2637c5150c4140f0a69bc791b80753784f4cdd505b6ec3b4","message":""}
+{"ts":"2026-07-25T23:48:53.918Z","author":"claude","author_source":"asserted","op":"note_add","patch":[{"op":"replace","path":"/metadata/updated_at","value":"2026-07-25T23:48:53.918Z"},{"op":"add","path":"/metadata/notes","value":[{"created_at":"2026-07-25T23:48:53.918Z","author":"claude","text":"REPRODUCED on pm 2026.7.25: `pm install github.com/unbraind/pm-github --project` fails with `Extension entry file is missing at \".../dist/index.js\"`. Root cause: `dist/` is in .gitignore and no build output is committed, and pm never runs a build when installing from a GitHub source - it copies the repository as-is."}]}],"before_hash":"8e6940b8ca0afdcb2637c5150c4140f0a69bc791b80753784f4cdd505b6ec3b4","after_hash":"e71f9e8a67690b5009bae246ed0f5a647461ba7b17b48ba7b9dac012803c282a"}
+{"ts":"2026-07-25T23:48:54.325Z","author":"claude","author_source":"asserted","op":"note_add","patch":[{"op":"add","path":"/metadata/notes/1","value":{"created_at":"2026-07-25T23:48:54.325Z","author":"claude","text":"FIX: document `pm install npm:pm-github`, verified working end to end. npm is the actual distribution channel for this package - the Daily Release workflow publishes it and `prepack` builds dist into the tarball - so the npm source needs no build output in git. Rejected committing dist/: build artifacts under version control invite drift (pm-web already tracks 72 dist files against 30 produced by a clean build) and add a conflict surface to the multi-agent merge workflow."}},{"op":"replace","path":"/metadata/updated_at","value":"2026-07-25T23:48:54.325Z"}],"before_hash":"e71f9e8a67690b5009bae246ed0f5a647461ba7b17b48ba7b9dac012803c282a","after_hash":"6dab1826e74920793d947a624961009b2f16a0bfd8989ae9c791c86f281bf5ce"}
+{"ts":"2026-07-25T23:48:54.685Z","author":"claude","author_source":"asserted","op":"note_add","patch":[{"op":"add","path":"/metadata/notes/2","value":{"created_at":"2026-07-25T23:48:54.684Z","author":"claude","text":"Bare-name installs do NOT reach npm: `pm install pm-github --project` fails with `Local extension source does not exist`, because a bare target resolves only a local directory or a bundled alias. The `npm:` prefix is required."}},{"op":"replace","path":"/metadata/updated_at","value":"2026-07-25T23:48:54.685Z"}],"before_hash":"6dab1826e74920793d947a624961009b2f16a0bfd8989ae9c791c86f281bf5ce","after_hash":"965f8fffe7372501e4d120d3b90c595a6e41b612c2116e300026c2f14b50d9e1"}
+{"ts":"2026-07-25T23:48:55.062Z","author":"claude","author_source":"asserted","op":"close","patch":[{"op":"replace","path":"/metadata/updated_at","value":"2026-07-25T23:48:55.062Z"},{"op":"replace","path":"/metadata/status","value":"closed"},{"op":"add","path":"/metadata/closed_at","value":"2026-07-25T23:48:55.062Z"},{"op":"add","path":"/metadata/close_reason","value":"Documented pm install npm:pm-github, verified working; GitHub source cannot work without committed build output"}],"before_hash":"965f8fffe7372501e4d120d3b90c595a6e41b612c2116e300026c2f14b50d9e1","after_hash":"595987ab6627c72c9f46bcf018122e6df07bca8518f301b0ea2ce12f560886be"}
diff --git a/.agents/pm/issues/pm-github-q6ql.toon b/.agents/pm/issues/pm-github-q6ql.toon
new file mode 100644
index 00000000..30b55420
--- /dev/null
+++ b/.agents/pm/issues/pm-github-q6ql.toon
@@ -0,0 +1,17 @@
+id: pm-github-q6ql
+title: "Documented install command fails: pm install github.com/unbraind/pm-github cannot resolve an entry file"
+description: ""
+type: Issue
+status: closed
+priority: 1
+tags: []
+created_at: "2026-07-25T23:48:53.463Z"
+updated_at: "2026-07-25T23:48:55.062Z"
+closed_at: "2026-07-25T23:48:55.062Z"
+author: claude
+notes[3]{created_at,author,text}:
+  "2026-07-25T23:48:53.918Z",claude,"REPRODUCED on pm 2026.7.25: `pm install github.com/unbraind/pm-github --project` fails with `Extension entry file is missing at \".../dist/index.js\"`. Root cause: `dist/` is in .gitignore and no build output is committed, and pm never runs a build when installing from a GitHub source - it copies the repository as-is."
+  "2026-07-25T23:48:54.325Z",claude,"FIX: document `pm install npm:pm-github`, verified working end to end. npm is the actual distribution channel for this package - the Daily Release workflow publishes it and `prepack` builds dist into the tarball - so the npm source needs no build output in git. Rejected committing dist/: build artifacts under version control invite drift (pm-web already tracks 72 dist files against 30 produced by a clean build) and add a conflict surface to the multi-agent merge workflow."
+  "2026-07-25T23:48:54.684Z",claude,"Bare-name installs do NOT reach npm: `pm install pm-github --project` fails with `Local extension source does not exist`, because a bare target resolves only a local directory or a bundled alias. The `npm:` prefix is required."
+close_reason: "Documented pm install npm:pm-github, verified working; GitHub source cannot work without committed build output"
+body: ""
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 5b65d02d..b78d0859 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -2,6 +2,10 @@
 
 ## Unreleased
 
+### Fixed
+
+- Documented install command fails: pm install github.com/unbraind/pm-github cannot resolve an entry file ([pm-github-q6ql](https://github.com/unbraind/pm-github/blob/main/.agents/pm/issues/pm-github-q6ql.toon))
+
 ### Other
 
 - Enable governance duplicate-detection advisory mode and adopt pm-cli 2026.7.25 ([pm-github-suxt](https://github.com/unbraind/pm-github/blob/main/.agents/pm/chores/pm-github-suxt.toon))
diff --git a/README.md b/README.md
index 76b56dbc..d324b42b 100644
--- a/README.md
+++ b/README.md
@@ -9,9 +9,14 @@ Import issues from any GitHub repo as pm items, export pm items back to GitHub (
 ## Installation
 
 ```bash
-pm install github.com/unbraind/pm-github --global
+pm install npm:pm-github --global
 ```
 
+> The `npm:` prefix is required. A bare `pm install pm-github` resolves only a local
+> directory or a bundled alias, never the registry, and a
+> `github.com/unbraind/pm-github` source cannot work either — pm copies a GitHub
+> source as-is without building it, and this repository does not commit `dist/`.
+
 ## Capabilities
 
 | SDK capability | What it provides |