vsmash · vsmash · May 12, 2026 · May 12, 2026 · May 12, 2026
diff --git a/README.md b/README.md
@@ -74,6 +74,7 @@ MAIASS_AI_MODE=off          # disable AI
 - **Changelog generation** — user-facing `CHANGELOG.md` and internal developer changelog
 - **Branch workflow** — feature → develop → staging → main with merge handling
 - **Ticket integration** — ticket numbers auto-detected from branch names (Jira `ABC-123`, GitHub/Trello `#123` or `123`)
+- **CI auto-version-bump** — one flag installs a workflow (GitHub Actions, GitLab CI, or Bitbucket Pipelines) that bumps the version automatically on every merge to your develop branch, with zero AI credit cost. See [the workflow docs](docs/workflow.md#-ci-auto-version-bump-on-pr-merge).
 - **First-run friendly** — works immediately with sensible defaults, no blocking setup
 
 ---

diff --git a/docs/commands.md b/docs/commands.md
@@ -61,6 +61,16 @@ maiass <command> [options] [arguments]
 
 See [configuration.md](./configuration.md#-automation-flags-vs-environment-variables) for how these flags relate to `MAIASS_AUTO_*` environment variables.
 
+### CI Setup Commands
+
+One-time flags that install or print a CI workflow that auto-bumps your version on every merge to your develop branch. See [CI Auto-Version-Bump on PR Merge](./workflow.md#-ci-auto-version-bump-on-pr-merge) for the full setup walkthrough.
+
+- `--create-gh-action` — Create `.github/workflows/maiass-version-bump.yml` in the current repo. Requires a `GH_PAT` secret with Contents/Metadata/Workflows scopes.
+- `--show-gl-excerpt` — Print a GitLab CI excerpt to stdout for you to merge into `.gitlab-ci.yml`. Requires a `GITLAB_TOKEN` CI variable with write scope.
+- `--show-bb-excerpt` — Print a Bitbucket Pipelines excerpt to stdout for you to merge into `bitbucket-pipelines.yml`. Requires either an SSH key with write access, or `BB_USERNAME` + `BB_APP_PASSWORD` variables.
+
+All three flags substitute `MAIASS_DEVELOPBRANCH` (from `.env.maiass`) into the rendered workflow at the moment they run — so the trigger fires on your actual develop branch, not the literal string `develop`. Defaults to `develop` when unset.
+
 ## Examples
 
 ```bash

diff --git a/docs/configuration.md b/docs/configuration.md
@@ -98,6 +98,8 @@ MAIASS_DEVELOPBRANCH=develop                   # Default: develop
 MAIASS_STAGINGBRANCH=staging                   # Default: staging
 ```
 
+> `MAIASS_DEVELOPBRANCH` is also substituted into the CI workflow templates produced by `maiass --create-gh-action`, `--show-gl-excerpt`, and `--show-bb-excerpt` at the moment those commands run. See [CI Auto-Version-Bump on PR Merge](./workflow.md#-ci-auto-version-bump-on-pr-merge) for the install walkthrough.
+
 ### 📦 Version Management
 ```bash
 # Version Files

diff --git a/docs/setup.md b/docs/setup.md
@@ -73,6 +73,18 @@ You should see:
 - No module warnings
 - Environment variables loaded from appropriate locations
 
+## Continuous Integration
+
+To auto-bump your project's version whenever a PR is merged to develop, MAIASS can install a ready-to-run CI workflow for GitHub Actions, GitLab CI, or Bitbucket Pipelines:
+
+```bash
+maiass --create-gh-action   # GitHub Actions
+maiass --show-gl-excerpt    # GitLab CI (prints excerpt)
+maiass --show-bb-excerpt    # Bitbucket Pipelines (prints excerpt)
+```
+
+The CI workflow disables AI (`MAIASS_AI_MODE=off`) so version bumps don't consume credits. See [CI Auto-Version-Bump on PR Merge](./workflow.md#-ci-auto-version-bump-on-pr-merge) for the auth setup per platform.
+
 ## Troubleshooting
 
 ### Module Type Warnings

diff --git a/docs/workflow.md b/docs/workflow.md
@@ -435,6 +435,88 @@ MAIASS_PLUGIN_PATH=wp-content/plugins/my-plugin/my-plugin.php
 MAIASS_THEME_PATH=wp-content/themes/my-theme/functions.php
 ```
 
+## 🔁 CI Auto-Version-Bump on PR Merge
+
+MAIASS can install a CI workflow that runs `maiass -a patch` automatically every time a pull request is merged into your develop branch — so version bumps never get forgotten.
+
+**One-time install per repository:**
+
+```bash
+# GitHub Actions
+maiass --create-gh-action
+
+# GitLab CI (prints to stdout — paste into your .gitlab-ci.yml)
+maiass --show-gl-excerpt
+
+# Bitbucket Pipelines (prints to stdout — paste into your bitbucket-pipelines.yml)
+maiass --show-bb-excerpt
+```
+
+**How it works:**
+
+1. You merge a PR into `develop` (or whatever you set `MAIASS_DEVELOPBRANCH` to).
+2. The workflow runs `npm install -g maiass` and then `maiass -a patch` on the merged commit.
+3. A new commit with the version bump and updated `CHANGELOG.md` is pushed back to the branch.
+4. `MAIASS_AI_MODE=off` is set inside the workflow — **no AI credits are consumed**.
+
+### GitHub Actions
+
+```bash
+maiass --create-gh-action
+```
+
+Writes `.github/workflows/maiass-version-bump.yml`. To finish setup:
+
+1. Create a fine-grained Personal Access Token at https://github.com/settings/personal-access-tokens with these scopes for the target repo:
+   - **Contents**: Read & Write
+   - **Metadata**: Read-only
+   - **Workflows**: Read & Write
+2. Add the PAT as a repository secret named `GH_PAT` (Settings → Secrets and variables → Actions).
+
+GitHub's trigger fires only on `pull_request.closed` with `merged == true`, so there's no risk of the bump commit re-triggering the workflow.
+
+### GitLab CI
+
+```bash
+maiass --show-gl-excerpt
+```
+
+Prints a job stage that runs on pushes to your develop branch. Merge it into your existing `.gitlab-ci.yml` (or use it as-is for a fresh project). To finish setup:
+
+1. Allow CI to push to your protected branch: **Settings → Repository → Protected branches**.
+2. Create a project access token (or personal access token) with write access.
+3. Add it as a masked, protected CI/CD variable named `GITLAB_TOKEN`.
+
+The excerpt includes a **double-bump guard**: it inspects the last commit's author and message, and exits early if it looks like a MAIASS bump commit. Required because GitLab can't trigger on PR-close specifically — it fires on every push to the branch, including its own bump commit.
+
+### Bitbucket Pipelines
+
+```bash
+maiass --show-bb-excerpt
+```
+
+Prints a pipeline step keyed on your develop branch. Merge it into your `bitbucket-pipelines.yml` (or use as-is). To finish setup:
+
+1. **Settings → Pipelines → SSH Keys** — add a key pair with write access, OR
+2. Use an app password: create one with **Repositories: Read & Write** scope, then add it as repository variables named `BB_USERNAME` and `BB_APP_PASSWORD` (secured).
+
+Like GitLab, Bitbucket can't gate on PR-merge specifically, so the same **double-bump guard** is included.
+
+### Develop branch name is baked in at install time
+
+The trigger filter in all three CI providers (`on.pull_request.branches:`, `only:`, `pipelines.branches:`) must be a YAML literal — there's no runtime escape hatch — so MAIASS substitutes your configured `MAIASS_DEVELOPBRANCH` into the rendered template at the moment you run `--create-gh-action` or `--show-*-excerpt`.
+
+- If `MAIASS_DEVELOPBRANCH=trunk` is set in `.env.maiass`, the installed workflow triggers on merges to `trunk`.
+- If unset, the workflow defaults to `develop` silently.
+
+If you rename your develop branch *after* installing the workflow, edit the trigger line in the installed file manually — re-running the install command will skip (it won't overwrite an existing workflow).
+
+### Notes
+
+- **Zero credit cost** — `MAIASS_AI_MODE: off` is set inside the workflow definition, so the version bump uses no AI tokens.
+- **No infinite loop** — GitHub's `merged == true` gate prevents re-triggering on the bump commit; GitLab and Bitbucket use the explicit double-bump guard.
+- **Combine with `--tag`** — change the workflow's `maiass -a patch` to `maiass -a patch --tag` if you also want a git tag created on every merge.
+
 ## 🤖 AI Integration Features
 
 ### Smart Commit Messages