README.md

@@ -186,6 +186,12 @@ Notes:
   [`docs/llm-workflow-runbooks.md`](docs/llm-workflow-runbooks.md) for the
   task-scoped, profile-based runbooks (create/review/merge/close, thin
   launchers, migration, fail-closed rules).
+- See [`docs/release-version-sop.md`](docs/release-version-sop.md) for the
+  operator SOP on cutting a versioned release (version bump, checks, merge,
+  `scripts/release-tag`, and cleanup).
+- See [`docs/linux-container-portability.md`](docs/linux-container-portability.md) for
+  Linux and container headless usage instructions, including environment-variable credential
+  loading and differences from macOS operator profiles.
 - For the **portable** version of this workflow (issue-first, isolated
   worktrees, no self-review/merge, profile safety, cleanup, fail-closed) that
   can be copied into any project, see the reusable skill

docs/linux-container-portability.md

@@ -0,0 +1,64 @@
+# Linux and Container Portability
+
+Gitea-Tools is fully supported on Linux and inside headless containers (such as CI/CD pipelines or Docker environments), but requires slightly different authentication configuration than standard macOS operator usage.
+
+## Setup Assumptions
+
+- **Python Environment:** Requires Python 3.9+ and `venv`.
+- **Keychain Access:** Linux environments typically lack macOS Keychain or a GUI prompt. All `type: "keychain"` profile authentication methods will fail in a headless Linux environment.
+- **Provenance:** The macOS `com.apple.provenance` extended attribute block does not exist on Linux.
+
+## Headless and Container MCP Server Usage
+
+When running the MCP server in a headless container or remote Linux environment, you cannot rely on interactive prompts or local Keychain. The server will run successfully out of the box as long as the profile is configured to use environment variables for authentication.
+
+## Environment-Variable Credential Loading
+
+Linux users must use environment variables for credential loading. Define your secrets in a gitignored `.env` file (e.g., `.env`) or inject them via standard container orchestration mechanisms.
+
+Example `.env`:
+```bash
+GITEA_TOKEN_MDCPS="your_actual_token_here"
+```
+**CRITICAL:** Never commit `.env` files containing actual tokens. The `.env` file is in `.gitignore`, but ensure it stays there.
+
+In your canonical profile JSON (e.g., `profiles.json`), configure authentication to use the `env` type rather than `keychain`:
+
+```json
+{
+  "profiles": {
+    "linux-ci": {
+      "base_url": "https://gitea.example.com",
+      "username": "ci_bot",
+      "auth": { "type": "env", "name": "GITEA_TOKEN_MDCPS" },
+      "execution_profile": "ci_worker"
+    }
+  }
+}
+```
+
+This ensures the MCP server safely loads the secret directly from the process environment when `linux-ci` is activated.
+
+## Avoiding macOS Keychain Assumptions
+
+If you are a Linux user or configuring a container, do **not** use `{ "auth": { "type": "keychain", "id": "..." } }`. If you run a profile configured for keychain, the underlying `security find-generic-password` calls will fail.
+
+This setup is the primary difference from local operator profiles (e.g., `prgs-reviewer` on a developer's Macbook), which typically rely on `keychain` to avoid writing tokens to `.env` files locally. Both methods are safe when used properly in their intended environments.
+
+## macOS-Specific Features
+
+- **`scripts/clear-provenance`**: This script uses `xattr` to remove macOS-specific execution restrictions. It is not needed and will not work on Linux.
+- **`scripts/gitea-config-menu`**: The interactive menu depends on macOS Keychain integration for token storage. While the JSON editing parts might work, token storage will fail on Linux.
+
+## Running Tests on Linux
+
+Running the test suite on Linux works identically to macOS. The tests fully mock all network requests and keychain interactions, ensuring the test suite can execute securely in a headless CI environment without needing actual credentials.
+
+```bash
+python3 -m pytest tests/ -v
+```
+
+## Known Limitations
+
+- Multi-token switching in a single runtime is not currently supported (one token per process).
+- The interactive `gitea-config-menu` script is primarily tailored for macOS operators.