diff --git a/README.md b/README.md
index 9a597e8..b410f04 100644
--- a/README.md
+++ b/README.md
@@ -33,13 +33,13 @@ dotgithub init
 dotgithub init --output ./my-workflows
 ```
 
-### Add GitHub Actions
+### Add GitHub Actions (and generate TypeScript wrappers)
 
 ```bash
-# Add a specific action
+# Add a specific action and generate its TypeScript wrapper/types
 dotgithub add actions/checkout@v4
 
-# Add multiple actions
+# Add multiple actions and generate wrappers for each
 dotgithub add actions/setup-node@v4 actions/setup-python@v5
 ```
 
@@ -53,7 +53,7 @@ dotgithub synth
 ## Basic Usage
 
 1. **Initialize** your project with `dotgithub init`
-2. **Configure** actions in `dotgithub.json`
+2. **Add actions** with `dotgithub add ...` (this generates TypeScript action wrappers and updates config)
 3. **Write** your workflow logic in TypeScript
 4. **Synthesize** workflows with `dotgithub synth`
 
diff --git a/packages/cli/README.md b/packages/cli/README.md
index 915ee0e..dfa420c 100644
--- a/packages/cli/README.md
+++ b/packages/cli/README.md
@@ -20,7 +20,7 @@ npx @dotgithub/cli --help
 # Initialize DotGitHub config/files
 dotgithub init
 
-# Add pinned GitHub Actions to your config
+# Add action and generate TypeScript wrapper/types for it
 dotgithub add actions/checkout@v4
 
 # Generate workflow files
@@ -37,7 +37,7 @@ dotgithub --help
 ## Typical TypeScript workflow
 
 1. `dotgithub init`
-2. `dotgithub add <org/repo@version>`
+2. `dotgithub add <org/repo@version>` (downloads metadata and generates TypeScript action wrappers)
 3. author/update your workflow constructs in **TypeScript**
 4. `dotgithub synth` to generate YAML
 5. commit generated workflow files