#!/usr/bin/env bash

#

# Create a draft documentation PR by auto-applying batched suggestions.

#

# Usage:

# script/docs-suggest-publish [--dry-run] [--model MODEL]

#

# This script:

# 1. Reads pending suggestions from the docs/suggestions-pending branch

# 2. Uses Droid to apply suggestions in batches (default 10 per batch)

# 3. Runs docs formatting

# 4. Validates docs build (action references, JSON schemas, links)

# 5. Creates a draft PR for human review/merge

# 6. Optionally resets the suggestions branch after successful PR creation

#

# Options:

# --dry-run Show what would be done without creating PR

# --keep-queue Don't reset the suggestions branch after PR creation

# --model MODEL Override Droid model used for auto-apply

# --batch-size N Suggestions per Droid invocation (default: 10)

# --skip-validation Skip the docs build validation step

# --verbose Show detailed progress

#

# Run this as part of the preview release workflow.

set -euo pipefail

DRY_RUN=false

KEEP_QUEUE=false

VERBOSE=false

SKIP_VALIDATION=false

BATCH_SIZE=10

MODEL="${DROID_MODEL:-claude-sonnet-4-5-latest}"

SUGGESTIONS_BRANCH="docs/suggestions-pending"

# Colors

RED='\033[0;31m'

GREEN='\033[0;32m'

YELLOW='\033[0;33m'

BLUE='\033[0;34m'

NC='\033[0m'

log() {

if [[ "$VERBOSE" == "true" ]]; then

echo -e "${BLUE}[docs-publish]${NC} $*" >&2

fi

}

error() {

echo -e "${RED}Error:${NC} $*" >&2

exit 1

}

# Parse arguments

while [[ $# -gt 0 ]]; do

case $1 in

--dry-run)

DRY_RUN=true

shift

;;

--keep-queue)

KEEP_QUEUE=true

shift

;;

--verbose)

VERBOSE=true

shift

;;

--model)

MODEL="$2"

shift 2

;;

--batch-size)

BATCH_SIZE="$2"

shift 2

;;

--skip-validation)

SKIP_VALIDATION=true

shift

;;

-h|--help)

head -30 "$0" | tail -28

exit 0

;;

*)

error "Unknown option: $1"

;;

esac

done

# Get repo root

REPO_ROOT="$(cd "$(dirname "$0")/.." && pwd)"

cd "$REPO_ROOT"

# Check if suggestions branch exists

log "Checking for suggestions branch..."

if ! git ls-remote --exit-code --heads origin "$SUGGESTIONS_BRANCH" > /dev/null 2>&1; then

echo "No pending suggestions found (branch $SUGGESTIONS_BRANCH doesn't exist)."

echo "Suggestions are queued automatically when PRs are merged to main."

exit 0

fi

# Fetch the suggestions branch

log "Fetching suggestions branch..."

git fetch origin "$SUGGESTIONS_BRANCH"

# Check for manifest

if ! git show "origin/$SUGGESTIONS_BRANCH:manifest.json" > /dev/null 2>&1; then

echo "No manifest found on suggestions branch."

exit 0

fi

# Read manifest

MANIFEST=$(git show "origin/$SUGGESTIONS_BRANCH:manifest.json")

SUGGESTION_COUNT=$(echo "$MANIFEST" | jq '.suggestions | length')

if [[ "$SUGGESTION_COUNT" -eq 0 ]]; then

echo "No pending suggestions in queue."

exit 0

fi

echo "Found $SUGGESTION_COUNT pending suggestion(s):"

echo ""

echo "$MANIFEST" | jq -r '.suggestions[] | " PR #\(.pr): \(.title)"'

echo ""

if [[ "$DRY_RUN" == "true" ]]; then

echo -e "${YELLOW}=== DRY RUN ===${NC}"

echo ""

echo "Would auto-apply suggestions to docs via Droid and create a draft PR."

echo "Model: $MODEL"

echo ""

# Show each suggestion file

for file in $(echo "$MANIFEST" | jq -r '.suggestions[].file'); do

echo "--- $file ---"

git show "origin/$SUGGESTIONS_BRANCH:$file" 2>/dev/null || echo "(file not found)"

echo ""

done

echo -e "${YELLOW}=== END DRY RUN ===${NC}"

echo ""

echo "Run without --dry-run to create the PR."

exit 0

fi

# Ensure clean working state (ignore untracked files with grep -v '??')

if [[ -n "$(git status --porcelain | grep -v '^??' || true)" ]]; then

error "Working directory has uncommitted changes. Please commit or stash first."

fi

REQUIRED_COMMANDS=(git gh jq droid)

if [[ "$SKIP_VALIDATION" != "true" ]]; then

REQUIRED_COMMANDS+=(mdbook)

fi

for command in "${REQUIRED_COMMANDS[@]}"; do

if ! command -v "$command" > /dev/null 2>&1; then

error "Required command not found: $command"

fi

done

# Remember current branch

ORIGINAL_BRANCH=$(git branch --show-current)

log "Current branch: $ORIGINAL_BRANCH"

# Create new branch for docs PR from latest main

git fetch origin main

DOCS_BRANCH="docs/preview-auto-$(date +%Y-%m-%d-%H%M%S)"

log "Creating docs branch: $DOCS_BRANCH"

git checkout -b "$DOCS_BRANCH" origin/main

TMPDIR=$(mktemp -d)

trap 'rm -rf "$TMPDIR"' EXIT

APPLY_SUMMARY_FILE="$TMPDIR/apply-summary.md"

touch "$APPLY_SUMMARY_FILE"

# Collect suggestion files into an array

SUGGESTION_FILES=()

while IFS= read -r file; do

SUGGESTION_FILES+=("$file")

done < <(echo "$MANIFEST" | jq -r '.suggestions[].file')

# Determine which PRs are already in the latest stable release.

# Suggestions queued with --preview may reference features that shipped in stable

# by the time this script runs, so their Preview callouts should be stripped.

STABLE_PRS=()

STABLE_TAG=$(git tag -l 'v*' --sort=-v:refname | grep -v 'pre' | head -1 || true)

if [[ -n "$STABLE_TAG" ]]; then

log "Latest stable release tag: $STABLE_TAG"

for file in "${SUGGESTION_FILES[@]}"; do

pr_num=$(echo "$MANIFEST" | jq -r --arg f "$file" '.suggestions[] | select(.file == $f) | .pr')

# Find the merge commit for this PR

merge_sha=$(gh pr view "$pr_num" --json mergeCommit --jq '.mergeCommit.oid' 2>/dev/null || true)

if [[ -n "$merge_sha" ]] && git merge-base --is-ancestor "$merge_sha" "$STABLE_TAG" 2>/dev/null; then

STABLE_PRS+=("$pr_num")

log "PR #$pr_num is in stable ($STABLE_TAG)"

fi

done

if [[ ${#STABLE_PRS[@]} -gt 0 ]]; then

echo -e "${YELLOW}Note:${NC} ${#STABLE_PRS[@]} suggestion(s) are for PRs already in stable ($STABLE_TAG)."

echo " Preview callouts will be stripped for: ${STABLE_PRS[*]}"

echo ""

fi

else

log "No stable release tag found, treating all suggestions as preview-only"

fi

# Determine which PRs touch code gated behind feature flags.

# Features behind flags aren't generally available and shouldn't be documented yet.

FLAGGED_PRS=()

FLAGS_FILE="$REPO_ROOT/crates/feature_flags/src/flags.rs"

if [[ -f "$FLAGS_FILE" ]]; then

# Extract feature flag struct names (e.g. SubagentsFeatureFlag)

FLAG_NAMES=$(grep -oE 'pub struct \w+FeatureFlag' "$FLAGS_FILE" | awk '{print $3}')

if [[ -n "$FLAG_NAMES" ]]; then

FLAG_PATTERN=$(echo "$FLAG_NAMES" | tr '\n' '|' | sed 's/|$//')

log "Feature flags found: $(echo "$FLAG_NAMES" | tr '\n' ' ')"

for file in "${SUGGESTION_FILES[@]}"; do

pr_num=$(echo "$MANIFEST" | jq -r --arg f "$file" '.suggestions[] | select(.file == $f) | .pr')

# Skip PRs already marked as stable (no need to double-check)

is_already_stable=false

for stable_pr in "${STABLE_PRS[@]+"${STABLE_PRS[@]}"}"; do

if [[ "$stable_pr" == "$pr_num" ]]; then

is_already_stable=true

break

fi

done

if [[ "$is_already_stable" == "true" ]]; then

continue

fi

# Check if the PR diff references any feature flag

pr_diff=$(gh pr diff "$pr_num" 2>/dev/null || true)

if [[ -n "$pr_diff" ]] && echo "$pr_diff" | grep -qE "$FLAG_PATTERN"; then

matched_flags=$(echo "$pr_diff" | grep -oE "$FLAG_PATTERN" | sort -u | tr '\n' ', ' | sed 's/,$//')

FLAGGED_PRS+=("$pr_num")

log "PR #$pr_num is behind feature flag(s): $matched_flags"

fi

done

if [[ ${#FLAGGED_PRS[@]} -gt 0 ]]; then

echo -e "${YELLOW}Note:${NC} ${#FLAGGED_PRS[@]} suggestion(s) are for features behind feature flags."

echo " These will be skipped: ${FLAGGED_PRS[*]}"

echo ""

fi

fi

else

log "Feature flags file not found, skipping flag detection"

fi

# Split into batches

TOTAL=${#SUGGESTION_FILES[@]}

BATCH_COUNT=$(( (TOTAL + BATCH_SIZE - 1) / BATCH_SIZE ))

if [[ "$BATCH_COUNT" -gt 1 ]]; then

echo "Processing $TOTAL suggestions in $BATCH_COUNT batches of up to $BATCH_SIZE..."

else

echo "Processing $TOTAL suggestions..."

fi

echo ""

for (( batch=0; batch<BATCH_COUNT; batch++ )); do

START=$(( batch * BATCH_SIZE ))

END=$(( START + BATCH_SIZE ))

if [[ "$END" -gt "$TOTAL" ]]; then

END=$TOTAL

fi

BATCH_NUM=$(( batch + 1 ))

BATCH_SUGGESTIONS_FILE="$TMPDIR/batch-${BATCH_NUM}-suggestions.md"

BATCH_PROMPT_FILE="$TMPDIR/batch-${BATCH_NUM}-prompt.md"

BATCH_SUMMARY_FILE="$TMPDIR/batch-${BATCH_NUM}-summary.md"

echo -e "${BLUE}Batch $BATCH_NUM/$BATCH_COUNT${NC} (suggestions $(( START + 1 ))-$END of $TOTAL)"

# Combine suggestion files for this batch, skipping flagged PRs and annotating stable PRs

BATCH_HAS_SUGGESTIONS=false

for (( i=START; i<END; i++ )); do

file="${SUGGESTION_FILES[$i]}"

pr_num=$(echo "$MANIFEST" | jq -r --arg f "$file" '.suggestions[] | select(.file == $f) | .pr')

# Skip PRs behind feature flags entirely

is_flagged=false

for flagged_pr in "${FLAGGED_PRS[@]+"${FLAGGED_PRS[@]}"}"; do

if [[ "$flagged_pr" == "$pr_num" ]]; then

is_flagged=true

break

fi

done

if [[ "$is_flagged" == "true" ]]; then

log "Skipping PR #$pr_num (behind feature flag)"

{

echo "### Skipped: PR #$pr_num"

echo ""

echo "This PR is behind a feature flag and was not applied."

echo ""

} >> "$APPLY_SUMMARY_FILE"

continue

fi

BATCH_HAS_SUGGESTIONS=true

# Check if PR is already in stable

is_stable=false

for stable_pr in "${STABLE_PRS[@]+"${STABLE_PRS[@]}"}"; do

if [[ "$stable_pr" == "$pr_num" ]]; then

is_stable=true

break

fi

done

{

echo "## Source: $file"

if [[ "$is_stable" == "true" ]]; then

echo ""

echo "> **ALREADY IN STABLE**: PR #$pr_num shipped in $STABLE_TAG."

echo "> Do NOT add Preview or Changed-in-Preview callouts for this suggestion."

echo "> Apply the documentation content only, without any preview-related callouts."

fi

echo ""

git show "origin/$SUGGESTIONS_BRANCH:$file" 2>/dev/null || error "Suggestion file missing: $file"

echo ""

echo "---"

echo ""

} >> "$BATCH_SUGGESTIONS_FILE"

done

# Skip this batch if all its suggestions were flagged

if [[ "$BATCH_HAS_SUGGESTIONS" == "false" ]]; then

echo -e " ${YELLOW}Batch $BATCH_NUM skipped (all suggestions behind feature flags)${NC}"

continue

fi

# Build auto-apply prompt for this batch

cat > "$BATCH_PROMPT_FILE" << 'EOF'

# Documentation Auto-Apply Request (Preview Release)

Apply all queued documentation suggestions below directly to docs files in this repository.

Before making edits, read and follow these rule files:

- `.rules`

- `docs/.rules`

## Required behavior

1. Apply concrete documentation edits (not suggestion text) to the appropriate files.

2. Edit only docs content files under `docs/src/` unless a suggestion explicitly requires another docs path.

3. For every docs file you modify, run a full-file brand voice pass (entire file, not only edited sections).

4. Enforce the brand rubric exactly; final file content must score 4+ on every criterion:

- Technical Grounding

- Natural Syntax

- Quiet Confidence

- Developer Respect

- Information Priority

- Specificity

- Voice Consistency

- Earned Claims

5. Keep SEO/frontmatter/linking requirements from the suggestions where applicable.

6. Keep preview callout semantics correct:

- Additive features: `> **Preview:** ...`

- Behavior modifications: `> **Changed in Preview (vX.XXX).** ...`

- **Exception**: Suggestions marked "ALREADY IN STABLE" must NOT get any preview callouts.

These features already shipped in a stable release. Apply the content changes only.

- Suggestions for features behind feature flags have been pre-filtered and excluded.

If you encounter references to feature-flagged functionality, do not document it.

7. If a suggestion is too ambiguous to apply safely, skip it and explain why in the summary.

8. **Do not invent `{#kb}` or `{#action}` references.** Only use action names that already

appear in the existing docs files you are editing. If unsure whether an action name is

valid, use plain text instead. The docs build validates all action references against

the compiled binary and will reject unknown names.

## Output format (after making edits)

Return markdown with:

- `## Applied Suggestions`

- `## Skipped Suggestions`

- `## Files Updated`

- `## Brand Voice Verification` (one line per updated file confirming full-file pass)

Do not include a patch in the response; apply edits directly to files.

## Queued Suggestions

EOF

cat "$BATCH_SUGGESTIONS_FILE" >> "$BATCH_PROMPT_FILE"

log "Running Droid auto-apply (batch $BATCH_NUM) with model: $MODEL"

if ! droid exec -m "$MODEL" -f "$BATCH_PROMPT_FILE" --auto high > "$BATCH_SUMMARY_FILE" 2>&1; then

echo "Droid exec output (batch $BATCH_NUM):"

cat "$BATCH_SUMMARY_FILE"

error "Droid exec failed on batch $BATCH_NUM. See output above."

fi

# Append batch summary

{

echo "### Batch $BATCH_NUM"

echo ""

cat "$BATCH_SUMMARY_FILE"

echo ""

} >> "$APPLY_SUMMARY_FILE"

echo -e " ${GREEN}Batch $BATCH_NUM complete${NC}"

done

echo ""

log "All batches completed, checking results..."

if [[ -n "$(git status --porcelain | grep -v '^??' | grep -vE '^.. docs/' || true)" ]]; then

error "Auto-apply modified non-doc files. Revert and re-run."

fi

if [[ -z "$(git status --porcelain docs/ | grep '^.. docs/src/' || true)" ]]; then

error "Auto-apply produced no docs/src changes."

fi

log "Running docs formatter"

./script/prettier --write

if [[ -z "$(git status --porcelain docs/ | grep '^.. docs/src/' || true)" ]]; then

error "No docs/src changes remain after formatting; aborting PR creation."

fi

# Validate docs build before creating PR

if [[ "$SKIP_VALIDATION" != "true" ]]; then

echo "Validating docs build..."

log "Generating action metadata..."

if ! ./script/generate-action-metadata > /dev/null 2>&1; then

echo -e "${YELLOW}Warning:${NC} Could not generate action metadata (cargo build may have failed)."

echo "Skipping docs build validation. CI will still catch errors."

else

VALIDATION_DIR="$TMPDIR/docs-validation"

if ! mdbook build ./docs --dest-dir="$VALIDATION_DIR" 2>"$TMPDIR/validation-errors.txt"; then

echo ""

echo -e "${RED}Docs build validation failed:${NC}"

cat "$TMPDIR/validation-errors.txt"

echo ""

error "Fix the errors above and re-run, or use --skip-validation to bypass."

fi

echo -e "${GREEN}Docs build validation passed.${NC}"

fi

echo ""

fi

# Build PR body from suggestions

PR_BODY_FILE="$TMPDIR/pr-body.md"

cat > "$PR_BODY_FILE" << 'EOF'

# Documentation Updates for Preview Release

This draft PR auto-applies queued documentation suggestions collected from

recently merged PRs.

## How to Use This PR

1. Review the applied changes file-by-file.

2. Verify brand voice on each touched file as a full-file pass.

3. Ensure docs use the correct callout type:

- Additive features: Preview callout

- Behavior modifications: Changed in Preview callout

4. Merge when ready.

## Auto-Apply Summary

EOF

cat "$APPLY_SUMMARY_FILE" >> "$PR_BODY_FILE"

cat >> "$PR_BODY_FILE" << 'EOF'

## Preview Callouts

Use the Preview callout for new/additive features:

```markdown

> **Preview:** This feature is available in Zed Preview. It will be included in the next Stable release.

```

Use this callout for behavior modifications to existing functionality:

```markdown

> **Changed in Preview (v0.XXX).** See [release notes](/releases#0.XXX).

```

---

## Pending Suggestions

EOF

# Append each suggestion to PR body

for file in $(echo "$MANIFEST" | jq -r '.suggestions[].file'); do

log "Adding $file to PR body..."

echo "" >> "$PR_BODY_FILE"

git show "origin/$SUGGESTIONS_BRANCH:$file" >> "$PR_BODY_FILE" 2>/dev/null || true

echo "" >> "$PR_BODY_FILE"

echo "---" >> "$PR_BODY_FILE"

done

# Add tracking info

cat >> "$PR_BODY_FILE" << EOF

## PRs Included

EOF

echo "$MANIFEST" | jq -r '.suggestions[] | "- [PR #\(.pr)](\(.file)): \(.title)"' >> "$PR_BODY_FILE"

cat >> "$PR_BODY_FILE" << 'EOF'

Release Notes:

- N/A

EOF

git add docs/

git commit -m "docs: Auto-apply preview release suggestions

Auto-applied queued documentation suggestions from:

$(echo "$MANIFEST" | jq -r '.suggestions[] | "- PR #\(.pr)"')

Generated with script/docs-suggest-publish for human review in draft PR."

# Push and create PR

log "Pushing branch..."

git push -u origin "$DOCS_BRANCH"

log "Creating PR..."

PR_URL=$(gh pr create \

--draft \

--title "docs: Apply preview release suggestions" \

--body-file "$PR_BODY_FILE")

echo ""

echo -e "${GREEN}PR created:${NC} $PR_URL"

# Reset suggestions branch if not keeping

if [[ "$KEEP_QUEUE" != "true" ]]; then

echo ""

echo "Resetting suggestions queue..."

git checkout --orphan "${SUGGESTIONS_BRANCH}-reset"

git rm -rf . > /dev/null 2>&1 || true

cat > README.md << 'EOF'

# Documentation Suggestions Queue

This branch contains batched documentation suggestions for the next Preview release.

Each file represents suggestions from a merged PR. At preview branch cut time,

run `script/docs-suggest-publish` to create a documentation PR from these suggestions.

## Structure

- `suggestions/PR-XXXXX.md` - Suggestions for PR #XXXXX

- `manifest.json` - Index of all pending suggestions

## Workflow

1. PRs merged to main trigger documentation analysis

2. Suggestions are committed here as individual files

3. At preview release, suggestions are collected into a docs PR

4. After docs PR is created, this branch is reset

EOF

mkdir -p suggestions

echo '{"suggestions":[]}' > manifest.json

git add README.md suggestions manifest.json

git commit -m "Reset documentation suggestions queue

Previous suggestions published in: $PR_URL"

# Force push required: replacing the orphan suggestions branch with a clean slate

git push -f origin "${SUGGESTIONS_BRANCH}-reset:$SUGGESTIONS_BRANCH"

git checkout "$ORIGINAL_BRANCH"

git branch -D "${SUGGESTIONS_BRANCH}-reset"

echo "Suggestions queue reset."

else

git checkout "$ORIGINAL_BRANCH"

echo ""

echo "Suggestions queue kept (--keep-queue). Remember to reset manually after PR is merged."

fi

echo ""

echo -e "${GREEN}Done!${NC}"

echo ""

echo "Next steps:"

echo "1. Review the draft PR and verify all auto-applied docs changes"

echo "2. Confirm full-file brand voice pass for each touched docs file"

echo "3. Mark ready for review and merge"