setup

Set Up Documentation Automation: $ARGUMENTS

Scaffolds the job that regenerates the documentation package after a pull request merges and opens a documentation PR against this same repository.

Required Skills

• engagement-scoping — resolve the output root and confirm the package exists before wiring automation to it

References

• config-resolution.md
• change-triggers-and-blast-radius.md

Phase 0 — Preflight

Read-only, run with the user's own gh credentials — which carry the admin scope CI does not have. Emits KEY=value and exits 0 on failure rather than degrading silently.

_RAW="$ARGUMENTS"
echo "### Setup Arguments"
echo "ARGS=$_RAW"

__dr="${CLAUDE_PLUGIN_ROOT:-}"
[ -x "$__dr/bin/dossier-managed-file.sh" ] || __dr=$({ echo plugins/dossier; ls -d "$HOME"/.claude/plugins/cache/synapti-marketplace/dossier/*/ 2>/dev/null | sort -Vr; echo "$HOME/.claude/plugins/marketplaces/synapti-marketplace/plugins/dossier"; } | while read -r __p; do [ -x "${__p%/}/bin/dossier-managed-file.sh" ] && { echo "${__p%/}"; break; }; done)

echo "### Plugin"
if [ ! -x "$__dr/bin/dossier-managed-file.sh" ]; then
  echo "SETUP_STATE=blocked"
  echo "SETUP_ERROR=dossier plugin scripts not found — reinstall or upgrade the plugin"
  true; exit 0
fi
echo "DOSSIER_ROOT=$__dr"
echo "PLUGIN_VERSION=$(jq -r '.version // "unknown"' "$__dr/.claude-plugin/plugin.json" 2>/dev/null)"

echo "### Repo"
REPO=$(gh repo view --json nameWithOwner --jq .nameWithOwner 2>/dev/null) || {
  echo "SETUP_STATE=blocked"
  echo "SETUP_ERROR=gh not authenticated — run 'gh auth login'"
  true; exit 0
}
echo "REPO=$REPO"
DB=$(gh repo view --json defaultBranchRef --jq .defaultBranchRef.name 2>/dev/null)
echo "DEFAULT_BRANCH=$DB"
echo "PRIVATE=$(gh repo view --json isPrivate --jq .isPrivate 2>/dev/null)"
echo "HAS_GITHUB_DIR=$([ -d .github ] && echo true || echo false)"
echo "HAS_GITLAB_CI=$([ -f .gitlab-ci.yml ] && echo true || echo false)"

echo "### The gotcha checks"
# GITHUB_TOKEN cannot open a PR unless this is enabled. Without it the branch
# pushes cleanly and `gh pr create` refuses — a successful push and no PR.
CAN_PR=$(gh api "repos/$REPO/actions/permissions/workflow" --jq '.can_approve_pull_request_reviews' 2>/dev/null) || CAN_PR="unknown"
echo "ACTIONS_CAN_CREATE_PRS=$CAN_PR"
echo "DEFAULT_WORKFLOW_PERMISSIONS=$(gh api "repos/$REPO/actions/permissions/workflow" --jq '.default_workflow_permissions' 2>/dev/null || echo unknown)"

ORG="${REPO%%/*}"
if gh api "orgs/$ORG" >/dev/null 2>&1; then
  echo "ORG_ACTIONS_CAN_CREATE_PRS=$(gh api "orgs/$ORG/actions/permissions/workflow" --jq '.can_approve_pull_request_reviews' 2>/dev/null || echo unknown)"
else
  echo "ORG_ACTIONS_CAN_CREATE_PRS=n/a"
fi

# Required checks make a GITHUB_TOKEN-created docs PR permanently unmergeable.
CHECKS=$(gh api "repos/$REPO/branches/$DB/protection" --jq '.required_status_checks.contexts | join(",")' 2>/dev/null) || CHECKS=""
echo "REQUIRED_CHECKS=${CHECKS:-none}"

echo "### Existing state"
echo "SECRETS=$(gh secret list --repo "$REPO" --json name --jq '[.[].name] | join(",")' 2>/dev/null || echo unreadable)"
echo "EXISTING_WORKFLOW=$([ -f .github/workflows/dossier-docs-refresh.yml ] && echo true || echo false)"
if [ -f .github/workflows/dossier-docs-refresh.yml ]; then
  "$__dr/bin/dossier-managed-file.sh" --verify .github/workflows/dossier-docs-refresh.yml 2>/dev/null || echo "MANAGED=unknown"
fi
OUTPUT_ROOT=$("$__dr/bin/dossier-resolve-config.sh" --default "docs/dossier" dossier.project.outputRoot 2>/dev/null)
echo "OUTPUT_ROOT=$OUTPUT_ROOT"
echo "PACKAGE_EXISTS=$([ -d "$OUTPUT_ROOT/00-control" ] && echo true || echo false)"
echo "FLOW_INSTALLED=$([ -f .claude/settings.flow.json ] && echo true || echo false)"
echo "MARKETPLACE_REF=$(gh api repos/synaptiai/synapti-marketplace/releases/latest --jq .tag_name 2>/dev/null || echo main)"

echo "### Merge cadence (for the cost conversation)"
echo "MERGES_LAST_4W=$(git log --merges --since='4 weeks ago' --oneline 2>/dev/null | wc -l | tr -d ' ')"
true