diff --git a/.changeset/green-coats-share.md b/.changeset/green-coats-share.md
new file mode 100644
index 0000000..783dc90
--- /dev/null
+++ b/.changeset/green-coats-share.md
@@ -0,0 +1,6 @@
+---
+"@dotgithub/core": patch
+"@dotgithub/cli": patch
+---
+
+Improve npm package documentation for both core and CLI with clearer usage examples, command flows, and direct documentation links.
diff --git a/packages/cli/README.md b/packages/cli/README.md
index d022032..915ee0e 100644
--- a/packages/cli/README.md
+++ b/packages/cli/README.md
@@ -1,16 +1,54 @@
 # @dotgithub/cli
 
-CLI for DotGitHub workflow scaffolding and synthesis.
+CLI for scaffolding, managing, and synthesizing DotGitHub workflows from TypeScript definitions.
 
 ## Install
 
 ```bash
 npm install -g @dotgithub/cli
-# or
+```
+
+Or run without installing globally:
+
+```bash
 npx @dotgithub/cli --help
 ```
 
+## Commands (quick overview)
+
+```bash
+# Initialize DotGitHub config/files
+dotgithub init
+
+# Add pinned GitHub Actions to your config
+dotgithub add actions/checkout@v4
+
+# Generate workflow files
+dotgithub synth
+```
+
+Aliases:
+
+```bash
+dgh --help
+dotgithub --help
+```
+
+## Typical TypeScript workflow
+
+1. `dotgithub init`
+2. `dotgithub add <org/repo@version>`
+3. author/update your workflow constructs in **TypeScript**
+4. `dotgithub synth` to generate YAML
+5. commit generated workflow files
+
 ## Docs
 
-- <https://github.com/azwebmaster/dotgithub#readme>
-- <https://github.com/azwebmaster/dotgithub/tree/main/docs>
+- Main docs: <https://github.com/azwebmaster/dotgithub#readme>
+- Guides: <https://github.com/azwebmaster/dotgithub/tree/main/docs>
+- CLI source/context: <https://github.com/azwebmaster/dotgithub/tree/main/packages/cli>
+
+## Repository
+
+- Source: <https://github.com/azwebmaster/dotgithub>
+- Issues: <https://github.com/azwebmaster/dotgithub/issues>
diff --git a/packages/core/README.md b/packages/core/README.md
index 3208354..3458bdc 100644
--- a/packages/core/README.md
+++ b/packages/core/README.md
@@ -1,6 +1,16 @@
 # @dotgithub/core
 
-Core library for DotGitHub: type-safe constructs and workflow generation utilities.
+Type-safe TypeScript library for defining and generating GitHub Actions workflows using DotGitHub constructs.
+
+## What this package is
+
+`@dotgithub/core` is the programmatic engine behind DotGitHub. It provides:
+
+- strongly typed workflow models
+- construct primitives for jobs/workflows/shared workflows
+- generation/synthesis helpers for writing `.github/workflows/*.yml`
+
+If you want to author reusable CI/CD logic in TypeScript (instead of hand-writing YAML), this is the package you use.
 
 ## Install
 
@@ -8,7 +18,42 @@ Core library for DotGitHub: type-safe constructs and workflow generation utiliti
 npm install @dotgithub/core
 ```
 
+## Quick example
+
+```ts
+import { createWorkflow } from '@dotgithub/core';
+
+const workflow = createWorkflow({
+  on: {
+    push: { branches: ['main'] },
+  },
+  jobs: {
+    test: {
+      'runs-on': 'ubuntu-latest',
+      steps: [
+        { uses: 'actions/checkout@v4' },
+        { run: 'npm ci' },
+        { run: 'npm test' },
+      ],
+    },
+  },
+});
+
+// synthesize with your DotGitHub pipeline
+```
+
+## When to use `@dotgithub/core` vs `@dotgithub/cli`
+
+- Use **`@dotgithub/core`** for library/SDK style usage in code.
+- Use **`@dotgithub/cli`** when you want command-driven setup and synthesis.
+
 ## Docs
 
-- <https://github.com/azwebmaster/dotgithub#readme>
-- <https://github.com/azwebmaster/dotgithub/tree/main/docs>
+- Main docs: <https://github.com/azwebmaster/dotgithub#readme>
+- Guides: <https://github.com/azwebmaster/dotgithub/tree/main/docs>
+- API/reference context: <https://github.com/azwebmaster/dotgithub/tree/main/packages/core>
+
+## Repository
+
+- Source: <https://github.com/azwebmaster/dotgithub>
+- Issues: <https://github.com/azwebmaster/dotgithub/issues>