diff --git a/.changeset/khaki-radios-kick.md b/.changeset/khaki-radios-kick.md
new file mode 100644
index 0000000..ad6be77
--- /dev/null
+++ b/.changeset/khaki-radios-kick.md
@@ -0,0 +1,6 @@
+---
+"@dotgithub/core": patch
+"@dotgithub/cli": patch
+---
+
+Add package-level README files and npm metadata links (homepage/repository/bugs) so published packages point back to project documentation.
diff --git a/packages/cli/README.md b/packages/cli/README.md
new file mode 100644
index 0000000..d022032
--- /dev/null
+++ b/packages/cli/README.md
@@ -0,0 +1,16 @@
+# @dotgithub/cli
+
+CLI for DotGitHub workflow scaffolding and synthesis.
+
+## Install
+
+```bash
+npm install -g @dotgithub/cli
+# or
+npx @dotgithub/cli --help
+```
+
+## Docs
+
+- <https://github.com/azwebmaster/dotgithub#readme>
+- <https://github.com/azwebmaster/dotgithub/tree/main/docs>
diff --git a/packages/cli/package.json b/packages/cli/package.json
index 54619bb..65fe6be 100644
--- a/packages/cli/package.json
+++ b/packages/cli/package.json
@@ -22,5 +22,14 @@
   "publishConfig": {
     "registry": "https://registry.npmjs.org",
     "access": "public"
+  },
+  "homepage": "https://github.com/azwebmaster/dotgithub#readme",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/azwebmaster/dotgithub.git",
+    "directory": "packages/cli"
+  },
+  "bugs": {
+    "url": "https://github.com/azwebmaster/dotgithub/issues"
   }
 }
diff --git a/packages/core/README.md b/packages/core/README.md
new file mode 100644
index 0000000..3208354
--- /dev/null
+++ b/packages/core/README.md
@@ -0,0 +1,14 @@
+# @dotgithub/core
+
+Core library for DotGitHub: type-safe constructs and workflow generation utilities.
+
+## Install
+
+```bash
+npm install @dotgithub/core
+```
+
+## Docs
+
+- <https://github.com/azwebmaster/dotgithub#readme>
+- <https://github.com/azwebmaster/dotgithub/tree/main/docs>
diff --git a/packages/core/package.json b/packages/core/package.json
index bdf5d56..05a6c0d 100644
--- a/packages/core/package.json
+++ b/packages/core/package.json
@@ -33,5 +33,14 @@
         "prettier"
       ]
     }
+  },
+  "homepage": "https://github.com/azwebmaster/dotgithub#readme",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/azwebmaster/dotgithub.git",
+    "directory": "packages/core"
+  },
+  "bugs": {
+    "url": "https://github.com/azwebmaster/dotgithub/issues"
   }
 }