erishforG · erishforG · Apr 22, 2026 · Apr 22, 2026 · Apr 22, 2026
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -0,0 +1,120 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.3.3] - 2026-04-22
+
+### Added
+- Global `--dry-run` flag for all mutating commands (start, ship, clean, sync, merge, rename)
+- Policy guard for protected branches and allowed ship targets (`[policy]` config)
+- `parsec doctor --ai` — output workflow rules as Markdown for AI agents
+- Standard error codes (E001–E013) with structured JSON error format
+- PR number stored as first-class field in operation log
+- `parsec ship --title` flag for custom PR titles
+
+### Fixed
+- reqwest 0.13 missing `rustls` TLS backend feature
+- rustls-webpki vulnerabilities (RUSTSEC-2026-0098/0099/0104)
+- `parsec open --pr` fails on GitHub Enterprise (hardcoded github.com)
+- Doctor command token handling and GHE support
+- `.atlassian-env` parser does not strip shell-style quotes
+- `unwrap()` panic paths in tracker and stack sync
+
+### Changed
+- Major dependency upgrades (reqwest 0.13, colored 3, indicatif 0.18, tabled 0.20, toml 1)
+- Extracted Jira config boilerplate into helper function
+- Ticket ID validation to prevent path traversal and invalid branch names
+
+## [0.3.2] - 2026-04-21
+
+### Fixed
+- Windows binary release upload (use bash shell)
+
+## [0.3.1] - 2026-04-21
+
+### Added
+- `parsec rename` command to re-ticket a workspace
+- `parsec create` and `parsec new-issue` for creating tracker issues from CLI
+- `parsec release` command for automated release workflow
+- `parsec doctor` for environment validation
+- `parsec list --full` with richer worktree metadata
+- `parsec init --install` for automatic shell integration setup
+- `parsec switch pr:NUMBER` to checkout PR branches
+- `parsec start --hook` for post-create automation
+- Pre-ship hooks support (`[hooks] pre_ship`)
+- `parsec ci` accepts multiple tickets
+- `parsec merge --batch` for merging multiple PRs sequentially
+- `parsec clean` supports cleaning a specific ticket
+- `parsec ship` auto-closes issues on merge
+- Automated multi-platform binary releases
+- Documentation site with guide and reference pages
+
+### Fixed
+- Jira integration improvements (config token, HTML error, status display)
+- Proper error propagation in CI
+
+### Changed
+- Output module refactored with `dispatch_output!` macro
+- Split monolithic `commands.rs` into per-command modules
+- Unified Create and NewIssue into single command
+- Typed response structs replace raw `serde_json::Value`
+- HTTP client timeout and retry for transient failures
+- Idempotency guarantees for ship/merge re-execution
+- Expanded integration test coverage
+
+## [0.3.0] - 2026-04-16
+
+### Added
+- `parsec board` — sprint as vertical Kanban board
+- `parsec ticket` command for tracker lookup with `--comment`
+- `parsec inbox` for viewing assigned tickets
+- `parsec init` and `parsec root` for shell integration
+- Automatic ticket status transitions
+- `parsec ship --base` flag and `default_base` config
+- `gh auth token` fallback for GitHub token resolution
+- Host-aware GitHub token resolution for GitHub Enterprise
+
+### Fixed
+- Merge/pr-status work with adopted branches
+- Conflicts detection with origin fallback
+- Prune stale remote-tracking references after merge
+
+### Security
+- Pinned GitHub Actions to SHA hashes
+- Added cargo audit job
+
+## [0.2.4] - 2026-04-15
+
+### Added
+- `parsec ci` to check CI/CD pipeline status
+- `parsec merge` to merge PRs from terminal
+- `parsec diff` to view worktree changes
+- `parsec stack` for stacked PR dependency tracking
+- `parsec start --branch` for existing branches
+
+## [0.2.3] - 2026-04-15
+
+### Added
+- `parsec open` to open PR or ticket page in browser
+- `parsec pr-status` for CI and review status
+- `parsec sync` to rebase/merge base branch
+- `parsec adopt` to import existing branches
+
+## [0.2.0] - 2026-04-14
+
+### Added
+- Initial release with core commands (start, list, status, ship, clean, conflicts, switch, log, undo)
+- Jira and GitHub Issues integration
+- `--json` output on all commands
+- Sibling and internal worktree layouts
+
+[0.3.3]: https://github.com/erishforG/git-parsec/compare/v0.3.2...v0.3.3
+[0.3.2]: https://github.com/erishforG/git-parsec/compare/v0.3.1...v0.3.2
+[0.3.1]: https://github.com/erishforG/git-parsec/compare/v0.3.0...v0.3.1
+[0.3.0]: https://github.com/erishforG/git-parsec/compare/v0.2.4...v0.3.0
+[0.2.4]: https://github.com/erishforG/git-parsec/compare/v0.2.3...v0.2.4
+[0.2.3]: https://github.com/erishforG/git-parsec/compare/v0.2.0...v0.2.3
+[0.2.0]: https://github.com/erishforG/git-parsec/releases/tag/v0.2.0
diff --git a/Cargo.toml b/Cargo.toml
@@ -7,6 +7,7 @@ description = "Git worktree lifecycle manager — ticket to PR in one command. P
 license = "MIT"
 repository = "https://github.com/erishforG/git-parsec"
 homepage = "https://erishforg.github.io/git-parsec/"
+documentation = "https://erishforg.github.io/git-parsec/"
 keywords = ["git", "worktree", "cli", "jira", "github"]
 categories = ["command-line-utilities", "development-tools"]
 readme = "README.md"

diff --git a/README.md b/README.md
@@ -323,6 +323,7 @@ $ parsec log
 | [`parsec create`](#parsec-create) | Create a new issue and optionally start a worktree |
 | [`parsec new-issue`](#parsec-new-issue) | Create a new issue (alias with extra options) |
 | [`parsec release`](#parsec-release-version) | Merge, tag, and create a GitHub Release |
+| [`parsec rename`](#parsec-rename-ticket---new-ticket-id) | Re-ticket a workspace to a different ticket ID |
 
 ---
 
@@ -1029,6 +1030,14 @@ $ parsec doctor --json
 {"checks":[...],"all_ok":false}
 ```
 
+**AI agent mode** — output parsec workflow rules as a Markdown document for AI agents to consume:
+
+```bash
+$ parsec doctor --ai
+# Outputs structured Markdown with workflow rules, command patterns,
+# and best practices for AI agents using parsec
+```
+
 ---
 
 ### `parsec create`
@@ -1119,12 +1128,38 @@ $ parsec release 0.3.1 --no-github-release
 
 ---
 
+### `parsec rename <ticket> --new <ticket-id>`
+
+Re-ticket an existing workspace to a different ticket ID. Renames the branch and updates internal state. Useful when a ticket is split or re-assigned.
+
+```
+parsec rename <ticket> --new <ticket-id>
+```
+
+| Option | Description |
+|--------|-------------|
+| `--new <ticket-id>` | New ticket ID to assign (required) |
+
+```bash
+# Re-ticket a workspace
+$ parsec rename PROJ-100 --new PROJ-200
+Renamed PROJ-100 → PROJ-200
+  Branch: feature/PROJ-100 → feature/PROJ-200
+  Path: /home/user/myapp.PROJ-200
+
+# JSON output
+$ parsec rename PROJ-100 --new PROJ-200 --json
+```
+
+---
+
 ## Global Flags
 
 These flags work on every command:
 
 | Flag | Description |
 |------|-------------|
+| `--dry-run` | Preview what a command would do without making changes |
 | `--json` | Machine-readable JSON output |
 | `-q, --quiet` | Suppress non-essential output |
 | `--repo <path>` | Target a different repository |
@@ -1244,6 +1279,11 @@ pre_ship = ["cargo test", "cargo clippy"]
 # tag_prefix = "v"       # Tag prefix (default: "v")
 # changelog = true       # Generate changelog in release notes
 
+[policy]
+# protected_branches = ["main", "develop", "release/*"]  # Branches that cannot be shipped to
+# allowed_ship_targets = ["develop"]                       # Restrict PR target branches
+# require_ci = false                                        # Require CI pass before merge
+
 [tracker.auto_transition]
 # on_start = "In Progress"   # Transition when `parsec start` runs
 # on_ship = "In Review"      # Transition when `parsec ship` runs
@@ -1272,6 +1312,36 @@ Token priority: `PARSEC_*_TOKEN` > platform-specific variables.
 
 ---
 
+## Error Codes
+
+When using `--json`, errors include a structured error code for programmatic handling:
+
+| Code | Meaning | Exit Code |
+|------|---------|-----------|
+| E001 | No authentication token configured | 2 |
+| E002 | CI checks failing | 4 |
+| E003 | Merge conflicts detected | 3 |
+| E004 | PR not mergeable | 5 |
+| E005 | Workspace not found | 5 |
+| E006 | Workspace already exists | 5 |
+| E007 | No active workspaces | 5 |
+| E008 | Pre-ship hook failed | 1 |
+| E009 | Policy violation | 6 |
+| E010 | PR not found | 5 |
+| E011 | Tracker not configured | 2 |
+| E012 | Ship partially completed | 1 |
+| E013 | Cannot undo operation | 1 |
+
+```bash
+# JSON error output example
+$ parsec ship PROJ-1234 --json 2>&1
+{"error":{"code":"E001","message":"No GitHub token configured","hint":"Set PARSEC_GITHUB_TOKEN or run gh auth login"}}
+$ echo $?
+2
+```
+
+---
+
 ## Comparison with Alternatives
 
 | Feature | parsec | GitButler | worktrunk | git worktree | git-town |
@@ -1294,6 +1364,40 @@ Token priority: `PARSEC_*_TOKEN` > platform-specific variables.
 
 ---
 
+## FAQ
+
+**How do I set up parsec with Jira?**
+Set `PARSEC_JIRA_TOKEN` (or `JIRA_PAT`) and configure `[tracker.jira]` in `~/.config/parsec/config.toml` with your `base_url` and `project`. Run `parsec config init` for interactive setup, or `parsec doctor` to validate.
+
+**How do I set up parsec with GitHub Issues?**
+Set `provider = "github"` under `[tracker]` in your config. Authentication uses `PARSEC_GITHUB_TOKEN`, `GITHUB_TOKEN`, `GH_TOKEN`, or `gh auth token` automatically.
+
+**Does parsec support GitLab?**
+Yes. parsec supports GitLab for both issue tracking and MR creation. Set `provider = "gitlab"` and configure `[tracker.gitlab]` with your `base_url`. Set `PARSEC_GITLAB_TOKEN` for authentication.
+
+**Can I use parsec without a ticket tracker?**
+Yes. Set `provider = "none"` or use `--title` with `parsec start` to skip tracker lookup entirely.
+
+**How do stacked PRs work?**
+Use `parsec start CHILD --on PARENT` to create dependent worktrees. `parsec ship` automatically sets the correct base branch. `parsec stack --sync` rebases the entire chain.
+
+**What happens if two worktrees modify the same file?**
+`parsec conflicts` detects cross-worktree file overlap before you push. It compares changed files across all active worktrees and warns about collisions.
+
+**Can I undo a ship or clean?**
+Yes. `parsec undo` reverses the last operation. For `ship`, it re-creates the worktree from the branch. For `clean`, it restores from the remote branch if still available.
+
+**How do I protect branches from accidental shipping?**
+Add a `[policy]` section to your config with `protected_branches` and `allowed_ship_targets`. parsec will reject operations that violate these rules.
+
+**Does parsec work with GitHub Enterprise?**
+Yes. parsec auto-detects GitHub Enterprise from the remote URL and routes API calls to the correct host. Token resolution is host-aware.
+
+**How do AI agents use parsec?**
+Every command supports `--json` for structured output. Run `parsec doctor --ai` to get a Markdown document with workflow rules and command patterns optimized for AI agent consumption.
+
+---
+
 ## License
 
 MIT
diff --git a/docs/guide/index.html b/docs/guide/index.html
@@ -945,6 +945,33 @@
     }
     .reveal.visible { opacity: 1; transform: translateY(0); }
   </style>
+  <meta name="twitter:card" content="summary">
+  <meta name="twitter:title" content="git-parsec Guide — Installation and Quick Start">
+  <meta name="twitter:description" content="Get started with git-parsec: installation, configuration, and your first ticket-to-PR workflow.">
+  <script type="application/ld+json">
+{
+  "@context": "https://schema.org",
+  "@type": "BreadcrumbList",
+  "itemListElement": [
+    {"@type": "ListItem", "position": 1, "name": "git-parsec", "item": "https://erishforg.github.io/git-parsec/"},
+    {"@type": "ListItem", "position": 2, "name": "Guide", "item": "https://erishforg.github.io/git-parsec/guide/"}
+  ]
+}
+</script>
+  <script type="application/ld+json">
+{
+  "@context": "https://schema.org",
+  "@type": "HowTo",
+  "name": "How to install and use git-parsec",
+  "description": "Install git-parsec and create your first ticket-driven worktree in under 2 minutes.",
+  "step": [
+    {"@type": "HowToStep", "name": "Install parsec", "text": "Run cargo install git-parsec, or download a pre-built binary from GitHub Releases."},
+    {"@type": "HowToStep", "name": "Configure your tracker", "text": "Run parsec config init to set up Jira, GitHub Issues, or GitLab integration."},
+    {"@type": "HowToStep", "name": "Start a workspace", "text": "Run parsec start TICKET-ID to create an isolated worktree for your ticket."},
+    {"@type": "HowToStep", "name": "Ship your work", "text": "Run parsec ship TICKET-ID to push, create a PR, and clean up in one step."}
+  ]
+}
+</script>
 </head>
 <body>
 
@@ -1041,7 +1068,7 @@ <h3>Via cargo (recommended)</h3>
 <span class="terminal-line">&nbsp;</span>
 <span class="terminal-line"><span class="comment"># Verify installation</span></span>
 <span class="terminal-line"><span class="prompt">$</span> <span class="command">parsec</span> <span class="flag">--version</span></span>
-<span class="terminal-line"><span class="info">  parsec 0.2.4</span></span>
+<span class="terminal-line"><span class="info">  parsec 0.3.3</span></span>
             </div>
           </div>
 
@@ -1593,10 +1620,10 @@ <h3>Release workflow with <code>parsec release</code></h3>
               <span class="terminal-title-label">parsec release</span>
             </div>
             <div class="terminal-body">
-<span class="terminal-line"><span class="prompt">$</span> <span class="command">parsec release</span> <span class="arg">0.3.0</span></span>
+<span class="terminal-line"><span class="prompt">$</span> <span class="command">parsec release</span> <span class="arg">0.3.3</span></span>
 <span class="terminal-line"><span class="success">✓</span> <span class="info">Merged develop → main</span></span>
-<span class="terminal-line"><span class="success">✓</span> <span class="info">Tagged </span><span class="link">v0.3.0</span></span>
-<span class="terminal-line"><span class="success">✓</span> <span class="info">GitHub Release: </span><span class="link">github.com/org/repo/releases/tag/v0.3.0</span></span>
+<span class="terminal-line"><span class="success">✓</span> <span class="info">Tagged </span><span class="link">v0.3.3</span></span>
+<span class="terminal-line"><span class="success">✓</span> <span class="info">GitHub Release: </span><span class="link">github.com/org/repo/releases/tag/v0.3.3</span></span>
 <span class="terminal-line">&nbsp;</span>
 <span class="terminal-line"><span class="comment"># Always preview first with --dry-run</span></span>
 <span class="terminal-line"><span class="prompt">$</span> <span class="command">parsec release</span> <span class="arg">0.4.0</span> <span class="flag">--dry-run</span></span>