create-projx 1.3.5 → 1.4.0

package/README.md

@@ -87,19 +87,17 @@ cd my-app
 npx create-projx@latest update
 ```
 
-If the template merges cleanly with your code, it's auto-committed — done. If there are differences, template files are written directly and you review with `git diff`:
+Updates use a 3-tier merge strategy:
 
-```bash
-git diff                              # see what changed
-git checkout -- path/to/file          # discard a change you don't want
-git add . && git commit -m "projx: update to vX.X.X"  # commit when ready
-```
+1. **Git merge** — if the template merges cleanly with your code, it's auto-committed. Done.
+2. **3-way merge** — if git merge fails, each file is merged individually using `git merge-file`. Your additions (extra deps, env vars, custom config) are preserved alongside template updates. Clean merges are auto-staged; only true conflicts need review.
+3. **Direct copy** — if no merge baseline exists, template files are written directly. You pick which changes to keep via an interactive prompt, and discarded files are automatically added to your skip list.
 
 Your custom files (controllers, pages, middleware) are never deleted. Files you created that don't exist in the template are always preserved.
 
 ### Skip Files
 
-If a file keeps getting overwritten on every update, add it to `.projx-component`:
+To skip component source files, add `skip` to `.projx-component`:
 
 ```json
 {
@@ -109,7 +107,17 @@ If a file keeps getting overwritten on every update, add it to `.projx-component
 }
 ```
 
-Skipped files are excluded from template updates. Tooling files (Dockerfile, eslint, tsconfig) still get updated.
+To skip root-level files (docker-compose, README), add `skip` to `.projx`:
+
+```json
+{
+  "version": "1.3.6",
+  "components": ["fastapi", "frontend"],
+  "skip": ["docker-compose.yml", "README.md"]
+}
+```
+
+Skipped files are excluded from template updates.
 
 ## Options
 
@@ -118,6 +126,11 @@ npx create-projx <name> [options]
 npx create-projx init
 npx create-projx add <components...>
 npx create-projx update
+npx create-projx diff
+npx create-projx pin <patterns...>
+npx create-projx unpin <patterns...>
+npx create-projx pin --list
+npx create-projx doctor [--fix]
 
 --components <list>    Comma-separated: fastapi,fastify,frontend,mobile,e2e,infra
 --no-git               Skip git init
@@ -126,6 +139,41 @@ npx create-projx update
 -h, --help             Show help
 ```
 
+### Preview Changes
+
+See what `update` would change before applying:
+
+```bash
+cd my-app
+npx create-projx diff
+```
+
+Shows file-by-file analysis: clean updates, files needing merge, user-only changes, and skipped files.
+
+### Pin / Unpin Files
+
+Skip files from future template updates without editing JSON:
+
+```bash
+npx create-projx pin backend/pyproject.toml      # skip this file
+npx create-projx pin "backend/src/**"             # skip with glob
+npx create-projx unpin backend/pyproject.toml     # allow updates again
+npx create-projx pin --list                       # show all pinned files
+```
+
+Files inside a component directory are added to that component's `.projx-component` skip list. Root-level files are added to `.projx` skip.
+
+### Health Check
+
+Diagnose issues with your projx setup:
+
+```bash
+npx create-projx doctor         # check everything
+npx create-projx doctor --fix   # auto-fix what's possible
+```
+
+Checks: config validity, component markers, baseline ref, stale worktrees, skip pattern coverage.
+
 ## Rename Component Directories
 
 Rename `fastapi/` to `backend/`? Just rename the folder — the `.projx-component` marker file moves with it. The `update` command auto-discovers where each component lives by scanning for these markers. No config changes needed.