[docs] docs: unbloat ephemerals reference

[github-actions]

Summary

Condenses the ephemerals reference page by converting bullet lists and bold-prefixed field descriptions into tighter prose. No behavioral or semantic changes.

Changes

docs/src/content/docs/reference/ephemerals.md

• stop-after formats: Merged bullet list of accepted date/time formats and the separate minimum-granularity note into a single inline sentence. Clarified that recompiling does not reset the stop time unless --refresh-stop-time is passed.
• Safe-outputs expiration formats: Replaced two-item bullet list (integer / relative time) with inline prose; reworded the sub-24-hour rounding note.
• Maintenance operations details: Replaced bold-prefixed bullet entries for update, upgrade, safe_outputs, create_labels, validate, activity_report, and forecast with individual plain paragraphs using inline code for operation names.
• Maintenance configuration fields: Converted bold field-name introductions for runs_on, action_failure_issue_expires, and disabled_jobs to inline-code-prefixed sentences; removed standalone heading.
• Related Documentation links: Standardised descriptions to use for prepositions instead of mixed - / — separators.

Type

docs — prose-only refactor; no API, schema, or behavioral changes.

Generated by PR Description Updater for #46288 · 29.1 AIC · ⌖ 5.44 AIC · ⊞ 4.7K · ◷

[github-actions]

Hey @app/github-actions 👋 — thanks for the documentation cleanup on ephemerals.md! Tightening verbose bullet lists and condensing option descriptions into prose is exactly the kind of maintenance that keeps reference docs readable.

One note flagged by the checklist:

• No test changes — this is a pure docs edit (45 lines across a single .md file), so no test coverage is expected here. This can be disregarded for a docs-only PR.

The PR is well-described, focused on a single file, and carries no dependency changes. Looks ready for review! 🎉

Generated by ✅ Contribution Check · 90.8 AIC · ⌖ 13.8 AIC · ⊞ 6.2K · ◷

[github-actions]

✅ Design Decision Gate 🏗️ completed the design decision gate check.

No ADR enforcement needed: PR #46288 does not have the 'implementation' label and has 0 new lines of code in business logic directories (threshold: 100).

[github-actions]

🧠 Matt Pocock Skills Reviewer has completed the skills-based review. ✅

[github-actions]

✅ PR Code Quality Reviewer completed the code quality review.

[github-actions]

✅ Test Quality Sentinel completed test quality analysis.

No test files were added or modified in this PR. Test Quality Sentinel skipped.

[Copilot]

Pull request overview

Condenses the ephemerals reference while retaining examples and configuration guidance.

Changes:

• Streamlines expiration format descriptions.
• Converts maintenance-operation bullets into prose.
• Simplifies configuration and related-documentation wording.

Show a summary per file

File	Description
docs/src/content/docs/reference/ephemerals.md	Condenses ephemeral workflow and maintenance documentation.

Review details

Tip

Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Comments suppressed due to low confidence (3)

docs/src/content/docs/reference/ephemerals.md:58

• Sub-day expirations are not rounded to one day when the expiration marker is calculated: actions/setup/js/ephemerals.cjs:108-110 adds the configured hours directly. Only maintenance-frequency selection rounds partial days (pkg/workflow/maintenance_workflow.go:246-250), and the parser also rejects durations below 2 hours. Please distinguish these behaviors.

Supported formats are an integer day count (for example, `7`) or a relative duration such as `2h`, `7d`, `2w`, `1m`, or `1y`. Values under 24 hours are rounded up to a 1-day minimum for expiration.

docs/src/content/docs/reference/ephemerals.md:115

• The generated activity-report job no longer runs three 1/7/30-day queries or fetches 1000 runs each. It performs one --start-date -1w --count 500 query, and there is no rate-limit branch that skips a 30-day query (pkg/workflow/maintenance_workflow_yaml.go:497-510). The reference should describe the current workflow.

`activity_report` runs `gh aw logs --format markdown` for the last 24 hours, 7 days, and 30 days (up to 1000 runs each), then creates `[aw] agentic status report` with each time range in a collapsible `<details>` block. Downloaded logs are cached under `./.cache/gh-aw/activity-report-logs`. The job has a 2-hour timeout and skips the 30-day query when the GitHub API is rate-limited.

docs/src/content/docs/reference/ephemerals.md:117

• The current forecast job does not warm the cache with gh aw logs --artifacts agent; it restores ./.github/aw/logs and invokes gh aw forecast directly (pkg/workflow/maintenance_workflow_yaml.go:594-615). Keeping the removed command in this condensed description makes the reference inaccurate.

`forecast` warms the forecast cache with `gh aw logs --artifacts agent`, runs `gh aw forecast --repo <owner/repo> --timeout 30 --json` with a 30-minute graceful computation timeout, and always creates a summary issue. Successful runs create `[aw] workflow forecast report`; timeouts and other failures create `[aw] workflow forecast report (error)`.

• Files reviewed: 1/1 changed files
• Comments generated: 1
• Review effort level: Medium

[github-actions]

Documentation-only refactor. All behavioral details (stop-after formats, minute-only restriction, --refresh-stop-time semantics, sub-24h expiry rounding, maintenance operation descriptions) are accurately preserved in the condensed prose. No blocking issues.

🔎 Code quality review by PR Code Quality Reviewer · 8.34 AIC · ⌖ 4.26 AIC · ⊞ 5.6K
_{Comment /review to run again}

[github-actions]

Skills-Based Review 🧠

Applied /grill-with-docs — changes look clean.

The condensation is well-executed: all behavioral details are preserved (stop-after semantics, expiry rounding, maintenance ops), and the switch from nested bullets to prose paragraphs improves scannability without losing precision. No information loss detected.

🧠 Reviewed using Matt Pocock's skills by Matt Pocock Skills Reviewer · 10.5 AIC · ⌖ 4.27 AIC · ⊞ 6.7K
_{Comment /matt to run again}

[github-actions]

🎉 This pull request is included in a new release.

Release: v0.82.13