docs: clarify skill update flow

Author: Dmatut7

CHANGELOG.md

@@ -4,6 +4,7 @@
 
 - Added GitHub Actions npm Trusted Publishing workflow so tagged releases can publish without local npm tokens or OTP.
 - Added maintainer operations docs for releases, Trusted Publishing, and bundled Codex skill updates.
+- Clarified that users receive skill updates by reinstalling `codex-flow@latest`, rerunning `codex-flow install-codex`, and restarting Codex.
 
 ## 0.2.4 — 2026-06-05
 

README.md

@@ -27,6 +27,20 @@ Then open **any** project in Codex and say:
 GitHub fallback if npm is unavailable: `npm install -g github:Dmatut7/codex-flow`.
 `dongt` remains as a compatibility alias, but the public package and docs use `codex-flow`.
 
+## Update installed Codex skills
+
+When `codex-flow` ships updated skills, update both the npm package and the copied Codex skills:
+
+```bash
+npm install -g codex-flow@latest
+codex-flow install-codex
+codex-flow doctor
+# restart Codex App or Codex CLI
+```
+
+Why both steps? `npm install -g` updates the CLI package; `codex-flow install-codex` copies the bundled skills into `~/.codex/skills`.
+Codex reads those installed skill files after restart.
+
 ## What it feels like
 
 ![codex-flow animated demo](assets/codex-flow-demo.gif)

docs/CODEX_APP_CLI.md

@@ -33,7 +33,20 @@ codex-flow doctor
 
 Restart Codex App or Codex CLI after installing the skill.
 
-## 3. Use it in any project
+## 3. Update the installed skills later
+
+If `codex-flow` releases updated skills, users who already installed it should run:
+
+```bash
+npm install -g codex-flow@latest
+codex-flow install-codex
+codex-flow doctor
+# restart Codex App or Codex CLI
+```
+
+`npm install -g` updates the package. `codex-flow install-codex` is still required because Codex uses copied files under `~/.codex/skills`.
+
+## 4. Use it in any project
 
 Open the target repository in Codex and say one of these:
 
@@ -52,7 +65,7 @@ Codex should:
 3. write `.codex-flow/journal/<task>.jsonl`,
 4. summarize the parallel branches and result.
 
-## 4. Resume after interruption
+## 5. Resume after interruption
 
 Run the same command again:
 
@@ -62,23 +75,23 @@ codex-flow run .codex-flow/generated/<task>.workflow.ts
 
 Completed nodes replay from the journal. Only unfinished or changed nodes call Codex again.
 
-## 5. Try without network first
+## 6. Try without network first
 
 ```bash
 codex-flow try
 ```
 
 `try` creates a starter workflow in the current project and forces the fake backend, so this works without Codex login or network.
 
-## 6. Membership vs API key
+## 7. Membership vs API key
 
 Default backend: `codex-sdk`.
 
 That uses your logged-in Codex / ChatGPT account. No OpenAI API key is needed for the default path.
 
 Only the optional `openai-responses` backend needs `OPENAI_API_KEY`.
 
-## 7. If Codex does not start a workflow
+## 8. If Codex does not start a workflow
 
 Use a direct trigger phrase:
 
@@ -101,7 +114,7 @@ codex-flow install-codex
 
 Restart Codex and try again.
 
-## 8. If the workflow fails
+## 9. If the workflow fails
 
 Most failures are in the generated workflow, not the engine. Ask Codex to fix the generated file and rerun the same command.
 
@@ -113,7 +126,7 @@ codex-flow run .codex-flow/generated/<task>.workflow.ts --backend fake
 codex-flow smoke --backend codex-sdk
 ```
 
-## 9. When to use it
+## 10. When to use it
 
 Use `codex-flow` for tasks that can be split:
 

docs/MAINTAINER_OPERATIONS.md

@@ -69,6 +69,26 @@ npx npm@^11.10.0 trust github codex-flow \
   --yes
 ```
 
+## How users receive updated Codex skills
+
+Important: publishing a new npm version does not automatically rewrite a user's installed Codex skill files.
+
+`codex-flow install-codex` copies the bundled skills from the installed package into the user's Codex home:
+
+- source: global npm package contents
+- target: `~/.codex/skills/dynamic-workflow`
+- target: `~/.codex/skills/business-defect-audit`
+- target: `~/.codex/skills/parallel-fix`
+
+So every user-facing skill update needs two user commands after the npm release:
+
+```bash
+npm install -g codex-flow@latest
+codex-flow install-codex
+```
+
+Then they should restart Codex App or Codex CLI. `codex-flow doctor` can confirm whether the installed skills are present/current.
+
 ## Updating Codex skills after someone changes this repo
 
 The bundled skills live in:
@@ -77,7 +97,7 @@ The bundled skills live in:
 - `codex-skill-business-audit/` → installs as `business-defect-audit`
 - `codex-skill-parallel-fix/` → installs as `parallel-fix`
 
-For users installed from npm:
+Short user-facing update instructions:
 
 ```bash
 npm install -g codex-flow@latest