@soleur/opencode 0.0.0-stage → 1.0.0

package/skills/provision-doppler/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: provision-doppler
+description: "This skill should be used when provisioning Doppler projects and OIDC identities for tenants."
+disable-model-invocation: true
+---
+
+<!-- soleur-cloud-mode:start -->
+**Cloud Mode (Devin):** before pipeline work run `bash "${CLAUDE_PLUGIN_ROOT}/scripts/cloud-detect.sh"`. If `CLAUDE_PLUGIN_ROOT` is unset (cloud exec shells do not export it), resolve the root by IDENTITY, never by script basename: for `d` in `"$HOME/.local/share/devin/cli/plugins/cache"` and `/opt/.devin/plugins`, skip unless `[ -d "$d" ]`, then `MANIFEST="$(find "$d" -path '*/.claude-plugin/plugin.json' -exec grep -l '"name"[[:space:]]*:[[:space:]]*"soleur"' {} + 2>/dev/null | head -1)"`, `ROOT="${MANIFEST%/.claude-plugin/plugin.json}"` — one resolution, two consumers: `$ROOT/scripts/cloud-detect.sh` and `$ROOT/scripts/precommit-guard.sh`. (Shape check, not authentication: a planted `{"name":"soleur"}` dir passes — ADR-179 A11.) `local` or `not-local:no-devin-env` proceeds normally; any other `not-local:<reason>` applies `<plugin-root>/devin/INSTRUCTIONS.md` §Cloud Mode: emit the `--banner`, fan out sequentially with `Reviewed-Coverage: sequential-fallback` disclosure (never claim an independent review ran), `message_user` ack before any secrets read or production mutation, and run `precommit-guard.sh` before any `git commit` — hooks do not fire in cloud.
+<!-- soleur-cloud-mode:end -->
+
+<!-- grok-harness-invoke:start -->
+**Grok Build (`plugins/soleur/lib/harness.ts` `invokeSkill()`):** Read this SKILL.md in this process and run it to completion. A one-segment `soleur:<name>` in this document names a SKILL — on Grok Build, Read `plugins/soleur/skills/<name>/SKILL.md` in this process; it is not a nested tool_use. A multi-segment id such as `soleur:<domain>:<name>` names an AGENT: spawn it, never Read it, and on Grok Build spawn_subagent takes the id with its colons replaced by hyphens (`agentIdToGrokSubagentType`). **Claude Code:** Skill tool for a skill (`soleur:<name>`), Task tool with `subagent_type` for an agent. Forbidden is executing a subset, not the Read.
+<!-- grok-harness-invoke:end -->
+
+# Provision Doppler
+
+Create a Doppler project + config via Terraform and configure an OIDC service-account-identity via the Doppler API for a tenant's deploy pipeline.
+
+## Art. 32 Pre-condition
+
+**MUST run on the operator's local machine. MUST NOT run in CI.** Bootstrap credentials are accepted via `read -s` (interactive terminal only) and never persisted to disk, env exports, or CLI args. The `read -s` call blocks non-interactive shells by design.
+
+## Usage
+
+```
+soleur:provision-doppler <tenant-slug> <tenant-org> <tenant-repo> [--dry-run]
+```
+
+| Argument | Required | Description |
+|----------|----------|-------------|
+| `tenant-slug` | Yes | Canonical tenant identifier (kebab-case, e.g. `acme-prd`) |
+| `tenant-org` | Yes | GitHub org owning the tenant repo (for OIDC trust binding) |
+| `tenant-repo` | Yes | GitHub repo name (for OIDC trust binding) |
+| `--dry-run` | No | Print TF plan + API commands without executing |
+
+## Execution
+
+Run the provisioning script:
+
+```bash
+bash "${CLAUDE_PLUGIN_ROOT}/skills/provision-doppler/scripts/provision-doppler.sh" <slug> <org> <repo> [--dry-run]
+```
+
+The script:
+
+1. Validates prerequisites (DPA gate, slug format, tool availability)
+2. Checks idempotency (warns if Doppler project already exists)
+3. Generates `provisioning/<slug>/doppler.tf` with R2 remote backend
+4. Emits a copy-pasteable `terraform apply` compound command with credential re-entry
+5. After operator confirms TF apply, configures OIDC service-account-identity via Doppler API
+6. Smoke-tests the service account
+7. Prints teardown commands and bootstrap revocation reminder
+
+## Sharp Edges
+
+- R2 backend has no state locking. Single operator at N=2. Coordinate manually if parallel applies ever become possible.
+- OIDC trust binding cannot be fully verified locally. Test via deploy workflow (runbook Step 9) after all provisioning.
+- The Doppler API for service accounts (`POST /v3/workplace/service_accounts`) has no CLI equivalent and no TF resource.

package/skills/provision-doppler/scripts/provision-doppler.sh

@@ -0,0 +1,358 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# (#7797) Refuse to run under shell tracing. UNCONDITIONAL, and DELIBERATELY not
+# the conditional DOPPLER_TOKEN non-emptiness arm the linter offers for this file
+# — that arm is vacuous by construction here. This script acquires the operator's
+# workplace-scoped Doppler personal token with `read -rs -p "Doppler personal
+# token: "` BELOW this point, so the variable is still empty at guard time, the
+# arm opens, and `bash -x` goes on to print `Authorization: Bearer dp.pt.…` at
+# every API call site. The linter cannot see that: its ACQUIRES set knows
+# `doppler secrets get` / `gh auth token` / `_TOKEN="$(`, not `read -rs`.
+# Stdout, not stderr, because agent runtimes surface stdout and swallow stderr
+# (knowledge-base/project/constitution.md > Code Style).
+case "$-" in
+  *x*)
+    printf '[FATAL] refusing to run under xtrace: this script handles a live credential and -x would print it (see #7797)\n'
+    exit 78
+    ;;
+esac
+
+# (#7873) `--disable` closes ~/.curlrc and `--noproxy '*'` closes the proxy vars,
+# but neither touches the env that subverts TLS ITSELF. SSLKEYLOGFILE writes the
+# session keys and the CA vars substitute the trust store, so a CURL_CA_BUNDLE
+# MITM of the workplace-scoped personal token works with every other guard intact.
+unset SSLKEYLOGFILE CURL_CA_BUNDLE SSL_CERT_FILE SSL_CERT_DIR CURL_HOME \
+      HOSTALIASES LOCALDOMAIN RES_OPTIONS
+
+SLUG=""
+TENANT_ORG=""
+TENANT_REPO=""
+DRY_RUN=false
+
+usage() {
+  echo "Usage: provision-doppler <tenant-slug> <tenant-org> <tenant-repo> [--dry-run]" >&2
+  exit 1
+}
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --dry-run) DRY_RUN=true; shift ;;
+    --help|-h) usage ;;
+    -*)        echo "Unknown flag: $1" >&2; usage ;;
+    *)
+      if [[ -z "$SLUG" ]]; then SLUG="$1"
+      elif [[ -z "$TENANT_ORG" ]]; then TENANT_ORG="$1"
+      elif [[ -z "$TENANT_REPO" ]]; then TENANT_REPO="$1"
+      else echo "Unexpected argument: $1" >&2; usage
+      fi
+      shift ;;
+  esac
+done
+
+[[ -n "$SLUG" ]] || { echo "Error: tenant-slug is required." >&2; usage; }
+[[ -n "$TENANT_ORG" ]] || { echo "Error: tenant-org is required." >&2; usage; }
+[[ -n "$TENANT_REPO" ]] || { echo "Error: tenant-repo is required." >&2; usage; }
+
+if ! [[ "$SLUG" =~ ^[a-z0-9]+(-[a-z0-9]+)*$ ]]; then
+  echo "Error: tenant-slug must be kebab-case (e.g. 'acme-prd')." >&2
+  exit 1
+fi
+
+if ! [[ "$TENANT_ORG" =~ ^[a-zA-Z0-9]([a-zA-Z0-9-]*[a-zA-Z0-9])?$ ]]; then
+  echo "Error: tenant-org must be a valid GitHub org name (alphanumerics and hyphens)." >&2
+  exit 1
+fi
+
+if ! [[ "$TENANT_REPO" =~ ^[a-zA-Z0-9._-]+$ ]]; then
+  echo "Error: tenant-repo must be a valid GitHub repo name." >&2
+  exit 1
+fi
+
+PROVISIONING_DIR="provisioning/${SLUG}/doppler"
+CREATED_RESOURCES=()
+
+cleanup() {
+  local exit_code=$?
+  echo ""
+  echo "=== Teardown commands (resources created during this run) ==="
+  if [[ ${#CREATED_RESOURCES[@]} -eq 0 ]]; then
+    echo "  (no resources were created)"
+  else
+    for res in "${CREATED_RESOURCES[@]}"; do
+      echo "  $res"
+    done
+  fi
+  echo ""
+  echo "Bootstrap cleanup: Revoke the Doppler personal token used for bootstrapping — it is no longer needed."
+  exit "$exit_code"
+}
+trap cleanup EXIT INT TERM
+
+# --- Pre-checks ---
+
+command -v doppler >/dev/null 2>&1 || { echo "Error: 'doppler' CLI not found. Install: https://docs.doppler.com/docs/install-cli" >&2; exit 1; }
+command -v curl >/dev/null 2>&1 || { echo "Error: 'curl' not found." >&2; exit 1; }
+command -v terraform >/dev/null 2>&1 || { echo "Error: 'terraform' not found." >&2; exit 1; }
+
+# --- DPA gate ---
+
+DPA_FILE="knowledge-base/legal/tenant-dpa-register.md"
+[[ -f "$DPA_FILE" ]] || { echo "DPA register not found at $DPA_FILE. Run from Soleur monorepo root." >&2; exit 3; }
+awk -F'|' -v slug="$SLUG" '/^\|/ { gsub(/^ +| +$/, "", $2); if ($2 == slug) found = ($8 ~ /^ *(dpa-signed|provisioning-in-progress) *$/) } END { exit !found }' "$DPA_FILE" \
+  || { echo "No active DPA row for '$SLUG'. Sign DPA (Step 0) first." >&2; exit 3; }
+
+# --- Idempotency check ---
+
+if grep -q "$SLUG" < <(doppler projects 2>/dev/null); then
+  echo "WARNING: Doppler project '$SLUG' already exists."
+  echo "  Continuing will regenerate TF config. Existing project is unchanged until 'terraform apply'."
+  echo ""
+fi
+
+# --- Generate TF config ---
+
+mkdir -p "$PROVISIONING_DIR"
+
+cat > "${PROVISIONING_DIR}/doppler.tf" <<TFEOF
+terraform {
+  required_version = ">= 1.6"
+
+  backend "s3" {
+    bucket                      = "soleur-terraform-state"
+    key                         = "tenants/${SLUG}/doppler.tfstate"
+    region                      = "auto"
+    endpoints                   = { s3 = "https://4d5ba6f096b2686fbdd404167dd4e125.r2.cloudflarestorage.com" }
+    skip_credentials_validation = true
+    skip_requesting_account_id  = true
+    skip_metadata_api_check     = true
+    skip_region_validation      = true
+    skip_s3_checksum            = true
+    use_path_style              = true
+    use_lockfile                = false
+  }
+
+  required_providers {
+    doppler = {
+      source  = "DopplerHQ/doppler"
+      version = "~> 1.21"
+    }
+  }
+}
+
+variable "doppler_bootstrap_token" {
+  description = "Doppler personal token for bootstrapping (re-entered at apply time)"
+  type        = string
+  sensitive   = true
+}
+
+provider "doppler" {
+  doppler_token = var.doppler_bootstrap_token
+}
+
+resource "doppler_project" "tenant" {
+  name        = "${SLUG}"
+  description = "Tenant project for ${SLUG}"
+}
+
+resource "doppler_config" "prd" {
+  project     = doppler_project.tenant.name
+  environment = "prd"
+  name        = "prd_tenant_${SLUG}"
+}
+TFEOF
+
+echo "Generated ${PROVISIONING_DIR}/doppler.tf"
+
+# --- Dry-run output ---
+
+if $DRY_RUN; then
+  echo ""
+  echo "=== DRY RUN — No changes will be made ==="
+  echo ""
+  echo "--- Generated Terraform config ---"
+  cat "${PROVISIONING_DIR}/doppler.tf"
+  echo ""
+  echo "--- Copy-pasteable TF apply command ---"
+  echo "read -rs -p 'Doppler token: ' TF_VAR_doppler_bootstrap_token && \\"
+  echo "  export TF_VAR_doppler_bootstrap_token && \\"
+  echo "  (cd ${PROVISIONING_DIR} && terraform init && terraform apply); \\"
+  echo "  unset TF_VAR_doppler_bootstrap_token"
+  echo ""
+  echo "--- OIDC service-account commands (run after TF apply) ---"
+  # These printed recipes carry a live bearer, so they must TEACH the confined
+  # form: `--disable` literally first (it aborts ~/.curlrc parsing, and later is
+  # too late) and `--noproxy '*'` (#7873).
+  echo "curl --disable --noproxy '*' -sS -X POST 'https://api.doppler.com/v3/workplace/service_accounts' \\"
+  echo "  -H 'Content-Type: application/json' \\"
+  echo "  -d '{\"name\": \"${SLUG}-deploy\", \"workplace_role\": {\"identifier\": \"viewer\"}}' \\"
+  echo "  --config - < <(printf 'header = \"Authorization: Bearer %s\"\\n' \"\$DOPPLER_TOKEN\")"
+  echo ""
+  echo "# Then configure OIDC trust with two-claim binding + grant project access"
+  echo ""
+  echo "--- Smoke-test ---"
+  echo "curl --disable --noproxy '*' -sS --config - 'https://api.doppler.com/v3/workplace/service_accounts' < <(printf 'header = \"Authorization: Bearer %s\"\\n' \"\$DOPPLER_TOKEN\") | jq '.service_accounts[] | select(.name == \"${SLUG}-deploy\")'"
+  echo ""
+  echo "--- Teardown ---"
+  echo "  doppler projects delete '${SLUG}' --yes"
+  echo "  # Revoke service account via dashboard: Settings → Service Accounts → ${SLUG}-deploy → Revoke"
+  echo "  rm -rf ${PROVISIONING_DIR}"
+  echo ""
+  echo "Next step: type /soleur:provision-github ${SLUG} <org> <reviewer> yourself (user-invoked; Soleur cannot run it, ADR-236)"
+  exit 0
+fi
+
+# --- Interactive flow ---
+
+echo ""
+echo "=== Doppler provisioning for '${SLUG}' ==="
+echo ""
+echo "This will:"
+echo "  1. Apply Terraform to create Doppler project '${SLUG}' + prd config"
+echo "  2. Create OIDC service-account '${SLUG}-deploy' via Doppler API"
+echo "  3. Configure OIDC trust binding (${TENANT_ORG}/${TENANT_REPO} + production environment)"
+echo ""
+
+echo "--- Step 1: Terraform apply ---"
+echo ""
+echo "Run this command in a separate terminal:"
+echo ""
+echo "  read -rs -p 'Doppler token: ' TF_VAR_doppler_bootstrap_token && \\"
+echo "    export TF_VAR_doppler_bootstrap_token && \\"
+echo "    (cd ${PROVISIONING_DIR} && terraform init && terraform apply); \\"
+echo "    unset TF_VAR_doppler_bootstrap_token"
+echo ""
+
+read -p "TF apply complete? Type 'yes': " ACK
+[[ "$ACK" == "yes" ]] || { echo "Aborted." >&2; exit 1; }
+
+# --- Verify TF apply ---
+
+if ! doppler projects get "$SLUG" --plain >/dev/null 2>&1; then
+  echo "Error: Doppler project '$SLUG' not found. TF apply may not have completed." >&2
+  exit 1
+fi
+
+CREATED_RESOURCES+=("doppler projects delete '${SLUG}' --yes")
+echo "Verified: Doppler project '$SLUG' exists."
+
+# --- Step 2: OIDC service-account via API (in subshell for credential quarantine) ---
+
+echo ""
+echo "--- Step 2: OIDC service-account ---"
+echo ""
+echo "Accepting Doppler personal token for API calls (same token used for TF apply)."
+read -rs -p "Doppler personal token: " DOPPLER_TOKEN
+echo ""
+
+(
+  export DOPPLER_TOKEN
+
+  # Token-shape guard (never echoes the value): the token is written into curl's stdin
+  # config below, so a quote or newline in it would inject a config directive. An unusable
+  # token makes zero curl calls and aborts the run non-zero, never a green provisioning.
+  _bearer_ok() { local LC_ALL=C; case "${1:-}" in ''|*[!A-Za-z0-9._~+/=-]*) return 1 ;; esac; }
+  if ! _bearer_ok "$DOPPLER_TOKEN"; then
+    echo "Error: the Doppler personal token is missing or has an unexpected shape; no request was sent." >&2
+    exit 1
+  fi
+
+  # ONE wrapper owns the transport flags (`--disable` first, `--noproxy '*'`), the guard
+  # and the header: the bearer rides curl's stdin config channel, never its argument list.
+  doppler_api() {
+    _bearer_ok "$DOPPLER_TOKEN" || return 1
+    curl --disable --noproxy '*' -sS "$@" --config - \
+      < <(printf 'header = "Authorization: Bearer %s"\n' "$DOPPLER_TOKEN")
+  }
+
+  # Payloads are HOISTED into variables rather than written inline. Each curl here
+  # sends a credential, and a multi-line `-d "{…}"` literal makes the invocation
+  # multi-shaped, which is what the destination-confinement linter mis-parses as an
+  # env-settable destination (#7873). The destinations are literal URLs — SA_SLUG
+  # comes from the previous response — so there is nothing to pin; hoisting removes
+  # the parse artifact by making every invocation single-shaped.
+  SA_PAYLOAD="{\"name\": \"${SLUG}-deploy\", \"workplace_role\": {\"identifier\": \"viewer\"}}"
+
+  SA_RESPONSE=$(
+    doppler_api -X POST "https://api.doppler.com/v3/workplace/service_accounts" \
+      -H "Content-Type: application/json" \
+      -d "$SA_PAYLOAD"
+  )
+
+  SA_SLUG=$(echo "$SA_RESPONSE" | grep -o '"slug":"[^"]*"' | head -1 | cut -d'"' -f4)
+  if [[ -z "$SA_SLUG" ]]; then
+    echo "Error: Failed to create service account. Response:" >&2
+    echo "$SA_RESPONSE" >&2
+    exit 1
+  fi
+
+  echo "Created service account: ${SLUG}-deploy (slug: $SA_SLUG)"
+
+  # --- Configure OIDC trust binding ---
+
+  # Hoisted for the same reason as SA_PAYLOAD above: the two-claim binding is the
+  # payload that made this invocation multi-shaped.
+  TRUST_PAYLOAD="{\"type\": \"oidc\", \"oidc_identity\": {"
+  TRUST_PAYLOAD="${TRUST_PAYLOAD}\"issuer\": \"https://token.actions.githubusercontent.com\","
+  TRUST_PAYLOAD="${TRUST_PAYLOAD}\"subject_claims\": {"
+  TRUST_PAYLOAD="${TRUST_PAYLOAD}\"repository_owner\": \"${TENANT_ORG}\","
+  TRUST_PAYLOAD="${TRUST_PAYLOAD}\"repository\": \"${TENANT_ORG}/${TENANT_REPO}\","
+  TRUST_PAYLOAD="${TRUST_PAYLOAD}\"environment\": \"production\"}}}"
+
+  TRUST_RESPONSE=$(
+    doppler_api -X POST "https://api.doppler.com/v3/workplace/service_accounts/${SA_SLUG}/identity" \
+      -H "Content-Type: application/json" \
+      -d "$TRUST_PAYLOAD"
+  )
+
+  if grep -q '"success"' <<<"$TRUST_RESPONSE"; then
+    echo "Configured OIDC trust: repository=${TENANT_ORG}/${TENANT_REPO}, environment=production"
+  else
+    echo "Warning: OIDC trust binding response:" >&2
+    echo "$TRUST_RESPONSE" >&2
+    echo "Verify manually in Doppler dashboard." >&2
+  fi
+
+  # --- Grant project access ---
+
+  GRANT_PAYLOAD="{\"project\": \"${SLUG}\", \"role\": \"viewer\"}"
+
+  GRANT_RESPONSE=$(
+    doppler_api -X POST "https://api.doppler.com/v3/workplace/service_accounts/${SA_SLUG}/projects" \
+      -H "Content-Type: application/json" \
+      -d "$GRANT_PAYLOAD"
+  )
+
+  if grep -q '"success"' <<<"$GRANT_RESPONSE"; then
+    echo "Granted service account access to project '${SLUG}'"
+  else
+    echo "Warning: Project grant response:" >&2
+    echo "$GRANT_RESPONSE" >&2
+  fi
+
+  # --- Smoke-test ---
+
+  echo ""
+  echo "--- Smoke-test ---"
+
+  SA_CHECK=$(
+    doppler_api "https://api.doppler.com/v3/workplace/service_accounts" \
+    | grep -o "\"name\":\"${SLUG}-deploy\""
+  )
+
+  if [[ -n "$SA_CHECK" ]]; then
+    echo "Smoke-test passed: service account '${SLUG}-deploy' exists."
+  else
+    echo "Warning: Could not verify service account '${SLUG}-deploy'. Check Doppler dashboard." >&2
+  fi
+)
+
+unset DOPPLER_TOKEN
+
+CREATED_RESOURCES+=("# Revoke service account: Settings → Service Accounts → ${SLUG}-deploy → Revoke")
+
+echo ""
+echo "NOTE: OIDC trust binding cannot be fully verified locally."
+echo "Test via deploy workflow (runbook Step 9) after all provisioning."
+echo ""
+echo "Next step: type /soleur:provision-github ${SLUG} <org> <reviewer> yourself (user-invoked; Soleur cannot run it, ADR-236)"

package/skills/provision-github/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: provision-github
+description: "This skill should be used when provisioning GitHub repos and environments for tenant workflows."
+disable-model-invocation: true
+---
+
+<!-- soleur-cloud-mode:start -->
+**Cloud Mode (Devin):** before pipeline work run `bash "${CLAUDE_PLUGIN_ROOT}/scripts/cloud-detect.sh"`. If `CLAUDE_PLUGIN_ROOT` is unset (cloud exec shells do not export it), resolve the root by IDENTITY, never by script basename: for `d` in `"$HOME/.local/share/devin/cli/plugins/cache"` and `/opt/.devin/plugins`, skip unless `[ -d "$d" ]`, then `MANIFEST="$(find "$d" -path '*/.claude-plugin/plugin.json' -exec grep -l '"name"[[:space:]]*:[[:space:]]*"soleur"' {} + 2>/dev/null | head -1)"`, `ROOT="${MANIFEST%/.claude-plugin/plugin.json}"` — one resolution, two consumers: `$ROOT/scripts/cloud-detect.sh` and `$ROOT/scripts/precommit-guard.sh`. (Shape check, not authentication: a planted `{"name":"soleur"}` dir passes — ADR-179 A11.) `local` or `not-local:no-devin-env` proceeds normally; any other `not-local:<reason>` applies `<plugin-root>/devin/INSTRUCTIONS.md` §Cloud Mode: emit the `--banner`, fan out sequentially with `Reviewed-Coverage: sequential-fallback` disclosure (never claim an independent review ran), `message_user` ack before any secrets read or production mutation, and run `precommit-guard.sh` before any `git commit` — hooks do not fire in cloud.
+<!-- soleur-cloud-mode:end -->
+
+<!-- grok-harness-invoke:start -->
+**Grok Build (`plugins/soleur/lib/harness.ts` `invokeSkill()`):** Read this SKILL.md in this process and run it to completion. A one-segment `soleur:<name>` in this document names a SKILL — on Grok Build, Read `plugins/soleur/skills/<name>/SKILL.md` in this process; it is not a nested tool_use. A multi-segment id such as `soleur:<domain>:<name>` names an AGENT: spawn it, never Read it, and on Grok Build spawn_subagent takes the id with its colons replaced by hyphens (`agentIdToGrokSubagentType`). **Claude Code:** Skill tool for a skill (`soleur:<name>`), Task tool with `subagent_type` for an agent. Forbidden is executing a subset, not the Read.
+<!-- grok-harness-invoke:end -->
+
+# Provision GitHub
+
+Create a GitHub repository + `production` Environment via Terraform, then drive the Soleur App install to the human consent screen.
+
+## Art. 32 Pre-condition
+
+**MUST run on the operator's local machine. MUST NOT run in CI.** The GitHub PAT is accepted via `read -s` (interactive terminal only) and never persisted to disk, env exports, or CLI args.
+
+## Usage
+
+```
+soleur:provision-github <tenant-slug> <tenant-org> <reviewer-github-username> [--dry-run]
+```
+
+| Argument | Required | Description |
+|----------|----------|-------------|
+| `tenant-slug` | Yes | Canonical tenant identifier (kebab-case) |
+| `tenant-org` | Yes | GitHub organization owning the tenant repo |
+| `reviewer-github-username` | Yes | GitHub username for required deployment reviewer |
+| `--dry-run` | No | Print TF plan + install URL without executing |
+
+## Execution
+
+```bash
+bash "${CLAUDE_PLUGIN_ROOT}/skills/provision-github/scripts/provision-github.sh" <slug> <org> <reviewer> [--dry-run]
+```
+
+The script:
+
+1. Validates prerequisites (DPA gate, slug format, `gh` auth, `terraform`)
+2. Checks idempotency (warns if repo already exists via `gh repo view`)
+3. Resolves numeric org-id for the App install URL
+4. Generates `provisioning/<slug>/github.tf` (repo + Environment + deployment policy + reviewer)
+5. Emits a copy-pasteable `terraform apply` compound command with credential re-entry
+6. After TF apply, presents the human consent gate for App installation (per ToS B.3)
+7. Verifies App install permissions via `gh api`
+8. Prints teardown commands including `bypass_actors` sweep reminder
+
+## Sharp Edges
+
+- GitHub TF provider requires explicit `token` auth — does NOT inherit from `gh` CLI.
+- R2 backend has no state locking. Single operator at N=2.
+- App install preserves human consent gate per GitHub ToS B.3. Skill does NOT automate the install click.
+- After uninstalling the App, sweep `bypass_actors` for ghost entries (GitHub does NOT auto-prune).
+- The `production` Environment + required reviewers is the security control that caps `actions:write` blast radius.