@simplysf/simply-gitlab 0.4.0 → 0.6.0

package/README.md

@@ -13,6 +13,12 @@ human-readable by default and raw JSON with `--json`, and every command that cha
 The same capabilities are available to AI agents through
 [`@simplysf/simply-gitlab-mcp`](https://github.com/SimplySF/simply-gitlab/tree/main/packages/simply-gitlab-mcp).
 
+## Documentation
+
+Guides and the full command reference: **https://simplysf.github.io/simply-cli/gitlab/**
+
+The guides also ship inside this package, under [`docs/`](docs).
+
 ## Install
 
 `@simplysf/simply-gitlab` is a plugin of the `simply` CLI, not a command of its own. Install the host; this
@@ -144,6 +150,7 @@ exitCode, status?, body?}}` — and nothing to stdout. Exit codes are identical
 - [`simply gitlab mr list`](#simply-gitlab-mr-list)
 - [`simply gitlab mr update`](#simply-gitlab-mr-update)
 - [`simply gitlab mr view`](#simply-gitlab-mr-view)
+- [`simply gitlab project create`](#simply-gitlab-project-create)
 - [`simply gitlab project list`](#simply-gitlab-project-list)
 - [`simply gitlab project view`](#simply-gitlab-project-view)
 - [`simply gitlab release list`](#simply-gitlab-release-list)
@@ -191,7 +198,7 @@ FLAG DESCRIPTIONS
     explicit export, and only GitLab connection variables are read from it. A path that cannot be read is an error.
 ```
 
-_See code: [lib/commands/gitlab/branch/create.js](https://github.com/SimplySF/simply-gitlab/blob/@simplysf/simply-gitlab@0.2.0/packages/simply-gitlab/lib/commands/gitlab/branch/create.js)_
+_See code: [lib/commands/gitlab/branch/create.js](https://github.com/SimplySF/simply-gitlab/blob/@simplysf/simply-gitlab@0.5.0/packages/simply-gitlab/lib/commands/gitlab/branch/create.js)_
 
 ## `simply gitlab branch list`
 
@@ -234,7 +241,7 @@ FLAG DESCRIPTIONS
     explicit export, and only GitLab connection variables are read from it. A path that cannot be read is an error.
 ```
 
-_See code: [lib/commands/gitlab/branch/list.js](https://github.com/SimplySF/simply-gitlab/blob/@simplysf/simply-gitlab@0.2.0/packages/simply-gitlab/lib/commands/gitlab/branch/list.js)_
+_See code: [lib/commands/gitlab/branch/list.js](https://github.com/SimplySF/simply-gitlab/blob/@simplysf/simply-gitlab@0.5.0/packages/simply-gitlab/lib/commands/gitlab/branch/list.js)_
 
 ## `simply gitlab ci environment list`
 
@@ -280,7 +287,7 @@ FLAG DESCRIPTIONS
     explicit export, and only GitLab connection variables are read from it. A path that cannot be read is an error.
 ```
 
-_See code: [lib/commands/gitlab/ci/environment/list.js](https://github.com/SimplySF/simply-gitlab/blob/@simplysf/simply-gitlab@0.2.0/packages/simply-gitlab/lib/commands/gitlab/ci/environment/list.js)_
+_See code: [lib/commands/gitlab/ci/environment/list.js](https://github.com/SimplySF/simply-gitlab/blob/@simplysf/simply-gitlab@0.5.0/packages/simply-gitlab/lib/commands/gitlab/ci/environment/list.js)_
 
 ## `simply gitlab ci job list`
 
@@ -324,7 +331,7 @@ FLAG DESCRIPTIONS
     explicit export, and only GitLab connection variables are read from it. A path that cannot be read is an error.
 ```
 
-_See code: [lib/commands/gitlab/ci/job/list.js](https://github.com/SimplySF/simply-gitlab/blob/@simplysf/simply-gitlab@0.2.0/packages/simply-gitlab/lib/commands/gitlab/ci/job/list.js)_
+_See code: [lib/commands/gitlab/ci/job/list.js](https://github.com/SimplySF/simply-gitlab/blob/@simplysf/simply-gitlab@0.5.0/packages/simply-gitlab/lib/commands/gitlab/ci/job/list.js)_
 
 ## `simply gitlab ci job log`
 
@@ -369,7 +376,7 @@ FLAG DESCRIPTIONS
     explicit export, and only GitLab connection variables are read from it. A path that cannot be read is an error.
 ```
 
-_See code: [lib/commands/gitlab/ci/job/log.js](https://github.com/SimplySF/simply-gitlab/blob/@simplysf/simply-gitlab@0.2.0/packages/simply-gitlab/lib/commands/gitlab/ci/job/log.js)_
+_See code: [lib/commands/gitlab/ci/job/log.js](https://github.com/SimplySF/simply-gitlab/blob/@simplysf/simply-gitlab@0.5.0/packages/simply-gitlab/lib/commands/gitlab/ci/job/log.js)_
 
 ## `simply gitlab ci variable list`
 
@@ -420,7 +427,7 @@ FLAG DESCRIPTIONS
     where this output is going.
 ```
 
-_See code: [lib/commands/gitlab/ci/variable/list.js](https://github.com/SimplySF/simply-gitlab/blob/@simplysf/simply-gitlab@0.2.0/packages/simply-gitlab/lib/commands/gitlab/ci/variable/list.js)_
+_See code: [lib/commands/gitlab/ci/variable/list.js](https://github.com/SimplySF/simply-gitlab/blob/@simplysf/simply-gitlab@0.5.0/packages/simply-gitlab/lib/commands/gitlab/ci/variable/list.js)_
 
 ## `simply gitlab commit create`
 
@@ -480,7 +487,7 @@ FLAG DESCRIPTIONS
     explicit export, and only GitLab connection variables are read from it. A path that cannot be read is an error.
 ```
 
-_See code: [lib/commands/gitlab/commit/create.js](https://github.com/SimplySF/simply-gitlab/blob/@simplysf/simply-gitlab@0.2.0/packages/simply-gitlab/lib/commands/gitlab/commit/create.js)_
+_See code: [lib/commands/gitlab/commit/create.js](https://github.com/SimplySF/simply-gitlab/blob/@simplysf/simply-gitlab@0.5.0/packages/simply-gitlab/lib/commands/gitlab/commit/create.js)_
 
 ## `simply gitlab commit diff`
 
@@ -522,7 +529,7 @@ FLAG DESCRIPTIONS
     explicit export, and only GitLab connection variables are read from it. A path that cannot be read is an error.
 ```
 
-_See code: [lib/commands/gitlab/commit/diff.js](https://github.com/SimplySF/simply-gitlab/blob/@simplysf/simply-gitlab@0.2.0/packages/simply-gitlab/lib/commands/gitlab/commit/diff.js)_
+_See code: [lib/commands/gitlab/commit/diff.js](https://github.com/SimplySF/simply-gitlab/blob/@simplysf/simply-gitlab@0.5.0/packages/simply-gitlab/lib/commands/gitlab/commit/diff.js)_
 
 ## `simply gitlab commit list`
 
@@ -573,7 +580,7 @@ FLAG DESCRIPTIONS
     explicit export, and only GitLab connection variables are read from it. A path that cannot be read is an error.
 ```
 
-_See code: [lib/commands/gitlab/commit/list.js](https://github.com/SimplySF/simply-gitlab/blob/@simplysf/simply-gitlab@0.2.0/packages/simply-gitlab/lib/commands/gitlab/commit/list.js)_
+_See code: [lib/commands/gitlab/commit/list.js](https://github.com/SimplySF/simply-gitlab/blob/@simplysf/simply-gitlab@0.5.0/packages/simply-gitlab/lib/commands/gitlab/commit/list.js)_
 
 ## `simply gitlab commit view`
 
@@ -614,7 +621,7 @@ FLAG DESCRIPTIONS
     explicit export, and only GitLab connection variables are read from it. A path that cannot be read is an error.
 ```
 
-_See code: [lib/commands/gitlab/commit/view.js](https://github.com/SimplySF/simply-gitlab/blob/@simplysf/simply-gitlab@0.2.0/packages/simply-gitlab/lib/commands/gitlab/commit/view.js)_
+_See code: [lib/commands/gitlab/commit/view.js](https://github.com/SimplySF/simply-gitlab/blob/@simplysf/simply-gitlab@0.5.0/packages/simply-gitlab/lib/commands/gitlab/commit/view.js)_
 
 ## `simply gitlab config apply`
 
@@ -681,7 +688,7 @@ FLAG DESCRIPTIONS
     the config does not target is an error rather than a silent no-op.
 ```
 
-_See code: [lib/commands/gitlab/config/apply.js](https://github.com/SimplySF/simply-gitlab/blob/@simplysf/simply-gitlab@0.2.0/packages/simply-gitlab/lib/commands/gitlab/config/apply.js)_
+_See code: [lib/commands/gitlab/config/apply.js](https://github.com/SimplySF/simply-gitlab/blob/@simplysf/simply-gitlab@0.5.0/packages/simply-gitlab/lib/commands/gitlab/config/apply.js)_
 
 ## `simply gitlab config export`
 
@@ -732,7 +739,7 @@ FLAG DESCRIPTIONS
     explicit export, and only GitLab connection variables are read from it. A path that cannot be read is an error.
 ```
 
-_See code: [lib/commands/gitlab/config/export.js](https://github.com/SimplySF/simply-gitlab/blob/@simplysf/simply-gitlab@0.2.0/packages/simply-gitlab/lib/commands/gitlab/config/export.js)_
+_See code: [lib/commands/gitlab/config/export.js](https://github.com/SimplySF/simply-gitlab/blob/@simplysf/simply-gitlab@0.5.0/packages/simply-gitlab/lib/commands/gitlab/config/export.js)_
 
 ## `simply gitlab config plan`
 
@@ -800,7 +807,7 @@ FLAG DESCRIPTIONS
     the config does not target is an error rather than a silent no-op.
 ```
 
-_See code: [lib/commands/gitlab/config/plan.js](https://github.com/SimplySF/simply-gitlab/blob/@simplysf/simply-gitlab@0.2.0/packages/simply-gitlab/lib/commands/gitlab/config/plan.js)_
+_See code: [lib/commands/gitlab/config/plan.js](https://github.com/SimplySF/simply-gitlab/blob/@simplysf/simply-gitlab@0.5.0/packages/simply-gitlab/lib/commands/gitlab/config/plan.js)_
 
 ## `simply gitlab file create`
 
@@ -852,7 +859,7 @@ FLAG DESCRIPTIONS
     explicit export, and only GitLab connection variables are read from it. A path that cannot be read is an error.
 ```
 
-_See code: [lib/commands/gitlab/file/create.js](https://github.com/SimplySF/simply-gitlab/blob/@simplysf/simply-gitlab@0.2.0/packages/simply-gitlab/lib/commands/gitlab/file/create.js)_
+_See code: [lib/commands/gitlab/file/create.js](https://github.com/SimplySF/simply-gitlab/blob/@simplysf/simply-gitlab@0.5.0/packages/simply-gitlab/lib/commands/gitlab/file/create.js)_
 
 ## `simply gitlab file update`
 
@@ -905,7 +912,7 @@ FLAG DESCRIPTIONS
     explicit export, and only GitLab connection variables are read from it. A path that cannot be read is an error.
 ```
 
-_See code: [lib/commands/gitlab/file/update.js](https://github.com/SimplySF/simply-gitlab/blob/@simplysf/simply-gitlab@0.2.0/packages/simply-gitlab/lib/commands/gitlab/file/update.js)_
+_See code: [lib/commands/gitlab/file/update.js](https://github.com/SimplySF/simply-gitlab/blob/@simplysf/simply-gitlab@0.5.0/packages/simply-gitlab/lib/commands/gitlab/file/update.js)_
 
 ## `simply gitlab file view`
 
@@ -951,7 +958,7 @@ FLAG DESCRIPTIONS
     explicit export, and only GitLab connection variables are read from it. A path that cannot be read is an error.
 ```
 
-_See code: [lib/commands/gitlab/file/view.js](https://github.com/SimplySF/simply-gitlab/blob/@simplysf/simply-gitlab@0.2.0/packages/simply-gitlab/lib/commands/gitlab/file/view.js)_
+_See code: [lib/commands/gitlab/file/view.js](https://github.com/SimplySF/simply-gitlab/blob/@simplysf/simply-gitlab@0.5.0/packages/simply-gitlab/lib/commands/gitlab/file/view.js)_
 
 ## `simply gitlab mr create`
 
@@ -1012,7 +1019,7 @@ FLAG DESCRIPTIONS
     explicit export, and only GitLab connection variables are read from it. A path that cannot be read is an error.
 ```
 
-_See code: [lib/commands/gitlab/mr/create.js](https://github.com/SimplySF/simply-gitlab/blob/@simplysf/simply-gitlab@0.2.0/packages/simply-gitlab/lib/commands/gitlab/mr/create.js)_
+_See code: [lib/commands/gitlab/mr/create.js](https://github.com/SimplySF/simply-gitlab/blob/@simplysf/simply-gitlab@0.5.0/packages/simply-gitlab/lib/commands/gitlab/mr/create.js)_
 
 ## `simply gitlab mr list`
 
@@ -1066,7 +1073,7 @@ FLAG DESCRIPTIONS
     explicit export, and only GitLab connection variables are read from it. A path that cannot be read is an error.
 ```
 
-_See code: [lib/commands/gitlab/mr/list.js](https://github.com/SimplySF/simply-gitlab/blob/@simplysf/simply-gitlab@0.2.0/packages/simply-gitlab/lib/commands/gitlab/mr/list.js)_
+_See code: [lib/commands/gitlab/mr/list.js](https://github.com/SimplySF/simply-gitlab/blob/@simplysf/simply-gitlab@0.5.0/packages/simply-gitlab/lib/commands/gitlab/mr/list.js)_
 
 ## `simply gitlab mr update`
 
@@ -1130,7 +1137,7 @@ FLAG DESCRIPTIONS
     explicit export, and only GitLab connection variables are read from it. A path that cannot be read is an error.
 ```
 
-_See code: [lib/commands/gitlab/mr/update.js](https://github.com/SimplySF/simply-gitlab/blob/@simplysf/simply-gitlab@0.2.0/packages/simply-gitlab/lib/commands/gitlab/mr/update.js)_
+_See code: [lib/commands/gitlab/mr/update.js](https://github.com/SimplySF/simply-gitlab/blob/@simplysf/simply-gitlab@0.5.0/packages/simply-gitlab/lib/commands/gitlab/mr/update.js)_
 
 ## `simply gitlab mr view`
 
@@ -1171,7 +1178,85 @@ FLAG DESCRIPTIONS
     explicit export, and only GitLab connection variables are read from it. A path that cannot be read is an error.
 ```
 
-_See code: [lib/commands/gitlab/mr/view.js](https://github.com/SimplySF/simply-gitlab/blob/@simplysf/simply-gitlab@0.2.0/packages/simply-gitlab/lib/commands/gitlab/mr/view.js)_
+_See code: [lib/commands/gitlab/mr/view.js](https://github.com/SimplySF/simply-gitlab/blob/@simplysf/simply-gitlab@0.5.0/packages/simply-gitlab/lib/commands/gitlab/mr/view.js)_
+
+## `simply gitlab project create`
+
+Create a project, blank or from a template.
+
+```
+USAGE
+  $ simply gitlab project create [--json] [-e <value>] [--gitlab-url <value>] [--gitlab-token <value>] [--dry-run] [--name
+    <value>] [--path <value>] [--namespace <value>] [--description <value>] [--visibility private|internal|public]
+    [--default-branch <value>] [--initialize-with-readme] [--topics <value>] [--template <value>] [--custom-template]
+    [--template-group <value>] [--template-project <value>] [--body <value> | --body-file <value>]
+
+FLAGS
+  --body=<value>              Raw JSON request body.
+  --body-file=<value>         Path to a file holding the raw JSON request body.
+  --custom-template           Look --template up among the instance's custom project templates rather than the built-in
+                              ones.
+  --default-branch=<value>    Name of the default branch.
+  --description=<value>       Project description.
+  --dry-run                   Print the request that would be sent and exit without sending it.
+  --initialize-with-readme    Create a first commit holding a README, so the repository is not empty.
+  --name=<value>              Project name. The path is derived from it when --path is not given.
+  --namespace=<value>         Group or user namespace to create the project in, by id or full path.
+  --path=<value>              Repository path, the URL slug. The name is derived from it when --name is not given.
+  --template=<value>          Template to create from: a built-in name, or with --custom-template or --template-group a
+                              custom one.
+  --template-group=<value>    Group whose custom project templates --template names, by id or full path.
+  --template-project=<value>  Custom template project to create from, by id or full path. Cannot be combined with
+                              --template.
+  --topics=<value>            Comma-separated topics to label the project with.
+  --visibility=<option>       Who can see the project.
+                              <options: private|internal|public>
+
+CONNECTION FLAGS
+  -e, --env-file=<value>      Path to a .env file holding connection settings.
+      --gitlab-token=<value>  [env: GITLAB_TOKEN] Personal, project, or group access token.
+      --gitlab-url=<value>    [env: GITLAB_URL] Base URL of the GitLab instance. Defaults to https://gitlab.com.
+
+GLOBAL FLAGS
+  --json  Format output as json.
+
+DESCRIPTION
+  Create a project, blank or from a template.
+
+  Creates the project in --namespace, or in the namespace of the token owner when none is given. Give it --name or
+  --path; GitLab derives whichever one is missing.
+
+  --template names one of the built-in templates GitLab ships, such as express or rails. To create from a custom
+  template instead, add --custom-template for one the instance administrator registered, --template-group for one in a
+  group, or use --template-project to name the template project itself by id or path — which GitLab prefers, because a
+  name can be ambiguous. Custom templates need a Premium or Ultimate instance.
+
+  A template is applied asynchronously: this command returns as soon as the project record exists, with an import status
+  of "scheduled", and the files arrive a few seconds later. Check "project view" until its import_status reads
+  "finished" before writing to the repository. --dry-run prints the exact request body; a namespace or template given as
+  a path is still looked up, so the printed ids are the ones that would be sent.
+
+EXAMPLES
+  $ simply gitlab project create --name new-service --namespace platform/apps
+
+  $ simply gitlab project create --name new-service --namespace platform/apps --template express --visibility internal
+
+  $ simply gitlab project create --name new-service --namespace platform/apps --template service-skeleton --template-group platform/templates
+
+  $ simply gitlab project create --path new-service --template-project platform/templates/service-skeleton --dry-run
+
+FLAG DESCRIPTIONS
+  -e, --env-file=<value>  Path to a .env file holding connection settings.
+
+    Loaded before anything else. Variables already present in the environment win, so the file never overrides an
+    explicit export, and only GitLab connection variables are read from it. A path that cannot be read is an error.
+
+  --namespace=<value>  Group or user namespace to create the project in, by id or full path.
+
+    Defaults to the namespace of the token owner.
+```
+
+_See code: [lib/commands/gitlab/project/create.js](https://github.com/SimplySF/simply-gitlab/blob/@simplysf/simply-gitlab@0.5.0/packages/simply-gitlab/lib/commands/gitlab/project/create.js)_
 
 ## `simply gitlab project list`
 
@@ -1218,7 +1303,7 @@ FLAG DESCRIPTIONS
     explicit export, and only GitLab connection variables are read from it. A path that cannot be read is an error.
 ```
 
-_See code: [lib/commands/gitlab/project/list.js](https://github.com/SimplySF/simply-gitlab/blob/@simplysf/simply-gitlab@0.2.0/packages/simply-gitlab/lib/commands/gitlab/project/list.js)_
+_See code: [lib/commands/gitlab/project/list.js](https://github.com/SimplySF/simply-gitlab/blob/@simplysf/simply-gitlab@0.5.0/packages/simply-gitlab/lib/commands/gitlab/project/list.js)_
 
 ## `simply gitlab project view`
 
@@ -1257,7 +1342,7 @@ FLAG DESCRIPTIONS
     explicit export, and only GitLab connection variables are read from it. A path that cannot be read is an error.
 ```
 
-_See code: [lib/commands/gitlab/project/view.js](https://github.com/SimplySF/simply-gitlab/blob/@simplysf/simply-gitlab@0.2.0/packages/simply-gitlab/lib/commands/gitlab/project/view.js)_
+_See code: [lib/commands/gitlab/project/view.js](https://github.com/SimplySF/simply-gitlab/blob/@simplysf/simply-gitlab@0.5.0/packages/simply-gitlab/lib/commands/gitlab/project/view.js)_
 
 ## `simply gitlab release list`
 
@@ -1298,7 +1383,7 @@ FLAG DESCRIPTIONS
     explicit export, and only GitLab connection variables are read from it. A path that cannot be read is an error.
 ```
 
-_See code: [lib/commands/gitlab/release/list.js](https://github.com/SimplySF/simply-gitlab/blob/@simplysf/simply-gitlab@0.2.0/packages/simply-gitlab/lib/commands/gitlab/release/list.js)_
+_See code: [lib/commands/gitlab/release/list.js](https://github.com/SimplySF/simply-gitlab/blob/@simplysf/simply-gitlab@0.5.0/packages/simply-gitlab/lib/commands/gitlab/release/list.js)_
 
 ## `simply gitlab search`
 
@@ -1353,7 +1438,7 @@ FLAG DESCRIPTIONS
     explicit export, and only GitLab connection variables are read from it. A path that cannot be read is an error.
 ```
 
-_See code: [lib/commands/gitlab/search.js](https://github.com/SimplySF/simply-gitlab/blob/@simplysf/simply-gitlab@0.2.0/packages/simply-gitlab/lib/commands/gitlab/search.js)_
+_See code: [lib/commands/gitlab/search.js](https://github.com/SimplySF/simply-gitlab/blob/@simplysf/simply-gitlab@0.5.0/packages/simply-gitlab/lib/commands/gitlab/search.js)_
 
 ## `simply gitlab tag list`
 
@@ -1400,7 +1485,7 @@ FLAG DESCRIPTIONS
     explicit export, and only GitLab connection variables are read from it. A path that cannot be read is an error.
 ```
 
-_See code: [lib/commands/gitlab/tag/list.js](https://github.com/SimplySF/simply-gitlab/blob/@simplysf/simply-gitlab@0.2.0/packages/simply-gitlab/lib/commands/gitlab/tag/list.js)_
+_See code: [lib/commands/gitlab/tag/list.js](https://github.com/SimplySF/simply-gitlab/blob/@simplysf/simply-gitlab@0.5.0/packages/simply-gitlab/lib/commands/gitlab/tag/list.js)_
 <!-- commandsstop -->
 
 ## License

package/docs/getting-started.md

@@ -0,0 +1,86 @@
+---
+title: Get Started
+description: Requirements, installation, and a first command for the Simply GitLab CLI.
+---
+
+## Requirements
+
+- Node.js 22 or later
+- A GitLab account on gitlab.com or a self-managed instance, and an access token
+
+## Install
+
+```sh
+npm install -g @simplysf/simply-cli
+```
+
+## Verify it worked
+
+```sh
+simply gitlab --help
+```
+
+## Get a token
+
+Create a personal access token under **Preferences › Access tokens** in GitLab, or a project or
+group access token from that project's or group's settings. Two scopes matter:
+
+| Scope      | What it allows                                           |
+| ---------- | -------------------------------------------------------- |
+| `read_api` | Everything on this site that reads. Nothing that writes. |
+| `api`      | Reads and writes.                                        |
+
+Start with `read_api`. It is not just a smaller permission — it is the only thing that makes a
+write structurally impossible, which matters as soon as a script or an agent is running these
+commands. See [Write safety](/guides/write-safety/).
+
+## Connect to your instance
+
+Every command reads its connection settings from environment variables, from flags, or from a
+`.env` file passed with `-e/--env-file`:
+
+```
+GITLAB_TOKEN=glpat-...
+GITLAB_URL=https://gitlab.example.com   # omit entirely for gitlab.com
+```
+
+`GITLAB_URL` defaults to `https://gitlab.com`, so a gitlab.com user needs only the token. See
+[Credentials](/guides/credentials/) for precedence between flags, environment, and file, and for
+trusting an internal certificate authority.
+
+## First commands
+
+Find a project you can reach, then look at its open merge requests:
+
+```sh
+simply gitlab project list --membership
+simply gitlab mr list --project group/project
+```
+
+Add `--json` to either to get the raw API payload instead of the formatted table.
+
+## Naming a project
+
+Every project-scoped command takes `-p/--project`, which accepts a numeric id or the full path.
+Both of these are the same project:
+
+```sh
+simply gitlab mr list --project 1234
+simply gitlab mr list --project group/subgroup/project
+```
+
+The path is URL-encoded for you — do not encode it yourself. If you work in one project most of
+the time, set `GITLAB_PROJECT` and drop the flag.
+
+## Where to go next
+
+- The [Command Reference](/reference/) lists every command by topic, with its flags and examples.
+- [Credentials](/guides/credentials/) covers tokens, precedence, and certificates.
+- [Write safety](/guides/write-safety/) explains `--dry-run`, `GITLAB_READ_ONLY`, and why a
+  `read_api` token is the only one of those that actually binds.
+- [Scripts and agents](/guides/scripting/) covers the `--json` contract and exit codes.
+- [MCP server](/guides/mcp-server/) gives an AI agent the same capabilities as tools, read-only by
+  default.
+- Want to contribute? See
+  [CONTRIBUTING.md](https://github.com/SimplySF/simply-gitlab/blob/main/CONTRIBUTING.md) in the
+  repo.

package/docs/guides/baselines.md

@@ -0,0 +1,186 @@
+---
+title: Configuration baselines
+description: Hold many GitLab projects to one standard - export a baseline from a project you like, see what differs across the rest, and converge them.
+---
+
+Fifty projects drift. One was created before you settled on squash merges, someone unprotected
+`main` to fix something and never put it back, and two never had an approval rule at all. There is
+no answer to "are these the same?" short of opening fifty tabs.
+
+A baseline is a JSON file saying what those projects should have in common, and three commands that
+read it:
+
+| Command                       | Writes? | What it does                                         |
+| ----------------------------- | ------- | ---------------------------------------------------- |
+| `simply gitlab config export` | no      | Emits a config from a project you already like       |
+| `simply gitlab config plan`   | no      | Reports, per project, what differs from the baseline |
+| `simply gitlab config apply`  | yes     | Converges each project onto the baseline             |
+
+## Start by exporting
+
+Do not write the file by hand. Export the project that already looks right and delete what you do
+not care about:
+
+```sh
+simply gitlab config export --project group/api > baseline.json
+```
+
+The output is deliberately verbose — every supported key, not a curated subset — because deleting a
+line is easier than discovering that a key exists. Variables come out as metadata only: keys,
+scopes, and flags, never values.
+
+## Point it at the rest
+
+The exported file targets only the project it came from. Widen it on purpose:
+
+```json
+{
+  "version": 1,
+  "targets": {
+    "groups": ["platform"],
+    "exclude": ["platform/sandbox", "platform/archived-*"]
+  },
+  "project": {
+    "settings": {
+      "merge_method": "ff",
+      "squash_option": "default_on",
+      "only_allow_merge_if_pipeline_succeeds": true
+    },
+    "protectedBranches": [{ "name": "main", "allow_force_push": false }],
+    "approvalRules": [{ "name": "Two maintainers", "approvals_required": 2, "usernames": ["alice", "bob"] }]
+  }
+}
+```
+
+`targets.groups` expands through subgroups. `exclude` takes a trailing `*` to drop a whole subtree.
+A project the token cannot see is a hard error, not a silent omission — a baseline that quietly
+skipped six of fifty would leave those six wrong with nobody knowing to look.
+
+## Read the plan
+
+```sh
+simply gitlab config plan --config ./baseline.json
+```
+
+```
+Targets: 50 project(s), 1 group(s).
+
+platform/api
+  settings
+    ~ merge_method  merge → ff
+    ~ only_allow_merge_if_pipeline_succeeds  false → true
+  protectedBranches
+    ~ main.allow_force_push  true → false
+    - legacy   (not pruned; set "prune": true on this section to remove it)
+
+platform/worker
+  ✓ matches the baseline
+
+50 target(s): 31 match, 19 differ.
+```
+
+Three things in that output are worth understanding.
+
+**Only what you declared is compared.** A project with forty settings the config never mentions
+shows nothing for them. That is what makes a baseline safe to point at projects that already exist:
+the blast radius is the set of keys you wrote down.
+
+**Drift you are not fixing is still shown.** `- legacy` is a protected branch that exists but is not
+in the config. By default nothing is deleted, and the line says so. Seeing what you are choosing not
+to correct is most of the value of running this across fifty projects.
+
+**A section can come back unsupported.** Approval rules, approval settings, and push rules are
+Premium/Ultimate. On an instance without them the section reports that and the rest still converges.
+
+## Apply it
+
+```sh
+simply gitlab config apply --config ./baseline.json --dry-run   # prints the plan, sends nothing
+simply gitlab config apply --config ./baseline.json
+```
+
+Apply executes exactly what the plan showed — the two are computed in one pass, so a preview is a
+guarantee rather than an approximation. A second run against a converged project sends no requests
+at all.
+
+Sections are applied in a fixed order: settings, protected branches, protected tags, approval
+settings, approval rules, push rules. That order exists because an approval rule scoped to `main`
+needs `main` protected before it can reference it.
+
+One project failing does not abandon the other forty-nine. There is no transaction across GitLab
+endpoints, so a project that fails part-way keeps the sections already applied; the summary says
+where it stopped, and `plan` afterwards shows what is left.
+
+## Per-project exceptions
+
+`overrides` is keyed by project path:
+
+```json
+"overrides": {
+  "platform/legacy-api": {
+    "project": {
+      "settings": { "merge_method": "merge" },
+      "approvalRules": [{ "name": "Two maintainers", "approvals_required": 1 }]
+    }
+  }
+}
+```
+
+Lists merge by a natural key — `name` for branches, tags, and rules; `key` plus `environment_scope`
+for variables — so an override adjusts one entry rather than restating the array. The rule above
+changes one number and inherits the usernames from the baseline.
+
+Set `"$replace": true` on a section to swap the list wholesale instead, for the project that needs
+genuinely different rules rather than adjusted ones.
+
+## Turning on pruning
+
+By default the config adds and corrects; it never deletes. When you are ready for a section to be
+authoritative, opt in:
+
+```json
+"protectedBranches": {
+  "prune": true,
+  "entries": [{ "name": "main", "allow_force_push": false }]
+}
+```
+
+Now an undeclared protected branch is removed. Adopt this section by section, after `plan` has shown
+you what it would take away — a first run against fifty existing projects with everything pruning
+could remove protections that predate the config.
+
+## Checking for drift in CI
+
+```sh
+simply gitlab config plan --config ./baseline.json --fail-on-drift
+```
+
+Exits `1` when anything differs, so a scheduled job tells you something drifted without anyone
+reading the output. `--json` returns the whole plan as structured data if you would rather track it
+over time:
+
+```sh
+simply gitlab config plan --config ./baseline.json --json | jq '.summary'
+```
+
+## CI/CD variables are reported, not written
+
+The config can declare which variables must exist and what flags they carry. `plan` reports the ones
+that are missing or wrong; `apply` does not touch them.
+
+That is the API, not caution. Creating a variable requires a value, and so does updating one — even
+to change `masked` from false to true. A variable created as `masked_and_hidden` will not return its
+value at all. There is no honest way to reconcile secrets from a file that, by design, holds none.
+
+Knowing that six projects are missing `DEPLOY_ENV` is still the question people actually ask; setting
+it is a person's job.
+
+## From an agent
+
+The MCP server exposes `gitlab_config_plan` and `gitlab_config_export`, so you can ask an agent
+"which of our projects are missing the two-approval rule?" and get an answer.
+
+There is deliberately no tool that applies a baseline. Changing settings across fifty projects is a
+deployment, not a tool call, and belongs to a person with the plan in front of them. An agent that
+should apply one can run the CLI, where it is a shell command you can see and approve. See the
+[MCP server guide](/guides/mcp-server/).