Update docs and CLI helpers across multiple components

AGENTS.md

@@ -27,30 +27,35 @@ Use the following skill for this repository. Skills are defined under `.agents/s
 
 All meaningful agent work SHOULD be documented.
 
-Optional metadata:
-- If you update an existing plan, research doc, or job record, you MAY add a `modified-date: YYYY-MM-DD` field to the front-matter.
-- Keep the original `date` value unchanged; `modified-date` is for the latest update.
+### Date Policy
 
-### Timezone
-
-- Unless a document or request specifies otherwise, record dates in UTC.
+- Use `created-date` for when the document first begins.
+- Use `modified-date` only when a later update is made.
+- Keep `created-date` unchanged after initial creation.
+- All dates are UTC calendar dates in `YYYY-MM-DD`.
+- Do not include time-of-day or timezone suffix in front-matter date fields.
+- When local and UTC dates differ, use the UTC date.
 
 ### Plan Documents
 
 Location:
+
 ```text
 docs/plans/plan-YYYY-MM-DD-<short-title>.md
 ```
 
 Notes:
+
 - Do not create or edit `docs/plan.md`.
-- Use the date for when the plan is created and a short, kebab-case title.
+- Use the creation date and a short, kebab-case title.
 
 Front-matter format:
+
 ```yaml
 ---
 title: "<plan title>"
-date: YYYY-MM-DD
+created-date: YYYY-MM-DD
+modified-date: YYYY-MM-DD # optional
 status: draft | active | completed
 agent: <agent name>
 ---
@@ -63,33 +68,39 @@ agent: <agent name>
 Use research docs for exploratory work that is not yet ready for a plan but may inform one.
 
 Location:
+
 ```text
 docs/research-YYYY-MM-DD-<short-title>.md
 ```
 
 Notes:
-- Use the date the research starts and a short, kebab-case title.
+
+- Use the creation date and a short, kebab-case title.
 - Keep scope focused on a single topic or question.
 - If research becomes actionable, create a plan doc and link to it.
 
 Front-matter format:
+
 ```yaml
 ---
 title: "<research title>"
-date: YYYY-MM-DD
+created-date: YYYY-MM-DD
+modified-date: YYYY-MM-DD # optional
 status: draft | in-progress | completed
 agent: <agent name>
 ---
 ```
 
 Suggested sections:
+
 - Goal
 - Key Findings
 - Implications or Recommendations
 - Open Questions (optional)
 - References (use footnote-style links)
 
 Traceability:
+
 - Research docs should include a short "Related Plans" section when applicable, with links to plan docs.
 - Plan docs should include a short "Related Research" section when applicable, with links to research docs.
 - Use those exact section titles for consistency.
@@ -102,15 +113,18 @@ Traceability:
 For concrete tasks or implementations, create a job record.
 
 Location:
+
 ```text
 docs/plans/jobs/YYYY-MM-DD-<short-title>.md
 ```
 
 Front-matter format:
+
 ```yaml
 ---
 title: "<job title>"
-date: YYYY-MM-DD
+created-date: YYYY-MM-DD
+modified-date: YYYY-MM-DD # optional
 status: draft | in-progress | completed | blocked
 agent: <agent name>
 ---
@@ -131,7 +145,7 @@ agent: <agent name>
 ## Writing Guidelines
 
 - Prefer clarity over verbosity
-- Record *what changed* and *why*
+- Record _what changed_ and _why_
 - Avoid repeating information already in other documents
 - Assume future agents will read this without prior context
 

Makefile

@@ -1,7 +1,8 @@
-.PHONY: help build man go-build install uninstall go-install go-uninstall clean
+.PHONY: help build man go-build install uninstall go-install go-uninstall markdown-fmt markdown-fmt-check clean
 
 # Build directory
 DIST_DIR := dist
+MD_FILES := $(shell git ls-files '*.md' | rg -v '^\.agents/skills/' || true)
 
 # Default target
 help:
@@ -22,6 +23,8 @@ help:
 	@echo ""
 	@echo "Development:"
 	@echo "  make help            Show this help message"
+	@echo "  make markdown-fmt    Format Markdown files with oxfmt"
+	@echo "  make markdown-fmt-check  Check Markdown formatting with oxfmt"
 	@echo ""
 
 # Build both binaries to dist/ directory
@@ -73,6 +76,24 @@ go-install:
 go-uninstall:
 	@bash ./scripts/go-uninstall.sh
 
+# Format Markdown files in-place using oxfmt
+.PHONY: markdown-fmt
+markdown-fmt:
+	@if [ -z "$(MD_FILES)" ]; then \
+		echo "No Markdown files found."; \
+	else \
+		npx oxfmt --write $(MD_FILES); \
+	fi
+
+# Check Markdown formatting using oxfmt
+.PHONY: markdown-fmt-check
+markdown-fmt-check:
+	@if [ -z "$(MD_FILES)" ]; then \
+		echo "No Markdown files found."; \
+	else \
+		npx oxfmt --check $(MD_FILES); \
+	fi
+
 # Clean up binaries in dist/ directory
 .PHONY: clean
 clean:

README.md

@@ -127,15 +127,13 @@ make go-uninstall
 
 > **Windows PATH Note:** If you install `gwtt.exe` into a custom folder (e.g., `C:\Users\<you>\bin`), add that folder to your PATH and open a new terminal to pick it up.
 
-
 > [!Note]
 > **Ownership Change (v0.0.7+)**
-> 
+>
 > The repository ownership changed after v0.0.6. The old `dev-pi2pie` path no longer exists, so use the new module path for all installs and imports:
-> 
+>
 > - **v0.0.7 and later:** `github.com/pi2pie/git-worktree-tasks`
 
-
 ## Binary Naming and Shell Configuration
 
 - Release assets ship the `gwtt` binary.
@@ -144,15 +142,16 @@ make go-uninstall
 
 Set up the `gwtt` alias for convenience:
 
-| Shell | Config File | Alias Syntax |
-|-------|-------------|--------------|
-| Bash  | `~/.bashrc` | `alias gwtt="git-worktree-tasks"` |
-| Zsh   | `~/.zshrc`  | `alias gwtt="git-worktree-tasks"` |
-| Fish  | `~/.config/fish/config.fish` | `alias gwtt git-worktree-tasks` |
+| Shell | Config File                  | Alias Syntax                      |
+| ----- | ---------------------------- | --------------------------------- |
+| Bash  | `~/.bashrc`                  | `alias gwtt="git-worktree-tasks"` |
+| Zsh   | `~/.zshrc`                   | `alias gwtt="git-worktree-tasks"` |
+| Fish  | `~/.config/fish/config.fish` | `alias gwtt git-worktree-tasks`   |
 
 After adding, reload your shell (`source ~/.bashrc`, `source ~/.zshrc`, or `exec fish`).
 
 **Alternative:** Create a symlink:
+
 ```bash
 ln -s $(which git-worktree-tasks) $(dirname $(which git-worktree-tasks))/gwtt
 ```
@@ -165,7 +164,7 @@ ln -s $(which git-worktree-tasks) $(dirname $(which git-worktree-tasks))/gwtt
 
 Settings resolve in this order (highest precedence first):
 
-1. `--theme` / `--mode` flags
+1. CLI flags (for example `--theme`, `--mode` / `-m`, `--mask-sensitive-paths`, `--no-mask-sensitive-paths`)
 2. Environment variables
 3. Project config (`gwtt.config.toml` or `gwtt.toml` in repo root)
 4. User config (`$HOME/.config/gwtt/config.toml`)
@@ -181,6 +180,9 @@ export GWTT_COLOR=0
 # Mode selection
 export GWTT_MODE=codex
 
+# Dry-run path masking (1/true/on/yes to enable, 0/false/off/no to disable)
+export GWTT_DRY_RUN_MASK_SENSITIVE_PATHS=1
+
 # List available themes
 gwtt --themes
 ```
@@ -209,6 +211,9 @@ color_enabled = true
 [table]
 grid = false
 
+[dry_run]
+mask_sensitive_paths = true # mask $HOME/%USERPROFILE% prefixes in --dry-run output
+
 [list]
 output = "table"
 field = "path"
@@ -238,12 +243,18 @@ worktree_only = false
 force_branch = false
 ```
 
+`[dry_run].mask_sensitive_paths` defaults to `true`. Set it to `false` if you need raw absolute paths in `--dry-run` output.  
+When enabled, home-prefixed paths are rendered as `$HOME/...` on POSIX and `%USERPROFILE%\\...` on Windows.
+You can override this per-invocation with `--mask-sensitive-paths=true|false`, `--no-mask-sensitive-paths`, or via `GWTT_DRY_RUN_MASK_SENSITIVE_PATHS`.
+For bool flags, prefer `--mask-sensitive-paths=false` (with `=`) rather than `--mask-sensitive-paths false`.
+
 ### Config File Location
 
 Project: `gwtt.config.toml` or `gwtt.toml` in the repo root  
 User: `$HOME/.config/gwtt/config.toml`
 
 **Minimal config:**
+
 ```toml
 [theme]
 name = "nord"
@@ -255,14 +266,15 @@ name = "nord"
 
 ### Commands Overview
 
-| Command   | Alias | Description |
-|-----------|-------|-------------|
-| `apply`   |       | Apply Codex worktree changes to the local checkout (codex mode only) |
-| `create`  |       | Create a worktree and branch for a task |
-| `list`    | `ls`  | List task worktrees |
-| `status`  |       | Show detailed worktree status |
-| `finish`  |       | Merge a task branch into target |
-| `cleanup` | `rm`  | Remove a task worktree and/or branch |
+| Command   | Alias | Description                                                          |
+| --------- | ----- | -------------------------------------------------------------------- |
+| `apply`   |       | Apply non-destructive changes between Codex worktree and local checkout (codex mode only) |
+| `overwrite` |     | Destructively replace destination with source changes in codex mode |
+| `create`  |       | Create a worktree and branch for a task                              |
+| `list`    | `ls`  | List task worktrees                                                  |
+| `status`  |       | Show detailed worktree status                                        |
+| `finish`  |       | Merge a task branch into target                                      |
+| `cleanup` | `rm`  | Remove a task worktree and/or branch                                 |
 
 ### Creating Worktrees
 
@@ -293,6 +305,7 @@ gwtt create "my-task" --dry-run
 | `--dry-run` | | Show git commands without executing |
 
 **Notes:**
+
 - The default base is the current local branch (for example `main`, `master`, or `dev`).
 - If you are in a detached HEAD state, you must pass `--base` explicitly.
 
@@ -398,19 +411,30 @@ gwtt finish "my-task" --cleanup --yes
 ### Applying Changes (Codex Mode)
 
 ```bash
-# Apply Codex worktree changes to local checkout
+# Non-destructive apply (default direction: worktree -> local)
 gwtt --mode codex apply <opaque-id>
 
-# Overwrite Codex worktree from local checkout without prompts
-gwtt --mode codex apply <opaque-id> --yes
+# Reverse non-destructive apply (local -> worktree)
+gwtt --mode codex apply <opaque-id> --to worktree
 
-# Preview without executing
+# Destructive overwrite (requires confirmation unless --yes)
+gwtt --mode codex overwrite <opaque-id> --to local
+gwtt --mode codex overwrite <opaque-id> --to worktree --yes
+
+# Compatibility alias for overwrite
+gwtt --mode codex apply <opaque-id> --to worktree --force --yes
+
+# Preview with structured plan + command echo
 gwtt --mode codex apply <opaque-id> --dry-run
 ```
 
 **Notes:**
+
 - In codex mode, `<opaque-id>` is the directory directly under `$CODEX_HOME/worktrees`.
-- If conflicts are detected, `gwtt` prompts to overwrite the Codex worktree (second confirmation). `--yes` skips prompts.
+- `apply` is non-destructive and will not switch direction automatically on conflict.
+- On conflict, `apply` exits with a next-step hint for `overwrite --to ...`.
+- `overwrite` resets/cleans the destination before transfer and is destructive by design.
+- `--dry-run` prints `plan`, `preflight`, and `actions` sections, then echoes the underlying git/copy operations.
 
 ### Cleanup
 
@@ -452,23 +476,23 @@ The `--output` (`-o`) and `--field` (`-f`) flags enable powerful shell integrati
 
 ### Output Formats
 
-| Format | Description | Available In |
-|--------|-------------|--------------|
+| Format  | Description                    | Available In     |
+| ------- | ------------------------------ | ---------------- |
 | `table` | Human-readable table (default) | `list`, `status` |
-| `json` | JSON array | `list`, `status` |
-| `csv` | CSV with headers | `list`, `status` |
-| `raw` | Single value, no decoration | `create`, `list` |
-| `text` | Styled text output (default) | `create` |
+| `json`  | JSON array                     | `list`, `status` |
+| `csv`   | CSV with headers               | `list`, `status` |
+| `raw`   | Single value, no decoration    | `create`, `list` |
+| `text`  | Styled text output (default)   | `create`         |
 
 ### Field Selection (for `--output raw`)
 
 When using `--output raw` with `list`, specify which field to output:
 
-| Field | Description |
-|-------|-------------|
-| `path` | Worktree path (default) |
-| `task` | Task name |
-| `branch` | Branch name |
+| Field    | Description             |
+| -------- | ----------------------- |
+| `path`   | Worktree path (default) |
+| `task`   | Task name               |
+| `branch` | Branch name             |
 
 ### Piping Examples
 
@@ -547,6 +571,7 @@ gwtt-new() {
 ### Raw Output Fallback
 
 When using `--output raw` with `list`:
+
 - If no matching worktree exists but the branch does, returns the main worktree path
 - Requires either a task filter or `--branch` flag
 
@@ -617,6 +642,7 @@ export PATH="$(go env GOPATH)/bin:$PATH"
 ### Shell Alias Not Working
 
 Reload your shell after adding the alias:
+
 ```bash
 source ~/.bashrc   # Bash
 source ~/.zshrc    # Zsh
@@ -637,4 +663,4 @@ This project is licensed under the MIT License — see the [LICENSE](https://git
 - Task names are slugified (lowercase, hyphens replace spaces)
 - Paths are relative by default; use `--abs` for absolute
 - Use `--dry-run` to preview git commands
-- Global flags: `--mode`, `--theme`, `--nocolor`, `--themes`
+- Global flags: `--mode` (`-m`), `--theme`, `--nocolor`, `--themes`