[joeyutong]

Linked issue: #1234

Purpose of change

Consistency and recovery guidance is spread across deployment and feature pages, while the configuration reference mixes option lookup with long feature tutorials. Add a dedicated Operations guide and separate usage guidance from the configuration reference.

• Add a Consistency guide covering mode selection, Java/Python/YAML setup, reuse of saved Action completions and durable call outcomes during recovery, limits on external effects, and Action State Store retention and cleanup.
• Organize the configuration reference into six task-based groups, sort keys within each group, and clarify loading precedence, parameter descriptions, and backend constraints. Preserve all 49 option names, types, and defaults.
• Move checkpoint-aligned Kafka cleanup prerequisites, procedures, and CLI guidance to Consistency and Trace Log usage guidance to Monitoring. Link feature pages directly to the shared guidance and clarify when external effects may repeat.

Tests

• Built the full site with Hugo 0.110.0 extended: 75 pages.
• Validated 3372 internal links and fragments across 80 generated HTML files, including retained anchors.
• Checked all 49 option names, types, and defaults against Java/Python definitions, and reviewed parameter descriptions against runtime behavior.
• Checked example syntax and API identifiers, and verified that cleanup prerequisites render in a collapsed block before the four-step procedure and command examples in a collapsed block immediately after it.
• git diff --check upstream/main passed.

Runtime tests were not rerun for this documentation-only change. Java examples were not compiled, and live-backend cleanup and cross-version recovery were not exercised.

API

No public API or configuration key, type, or default changes.

Documentation

• doc-needed
• doc-not-needed
• doc-included

Was this patch authored or co-authored using generative AI tooling?

• Yes
• No

Generated-by: Codex CLI 0.163.0-alpha.10.2 (GPT-6)

[wenjin272]

Thanks for improving the consistency and configuration guidance! I left two comments on the placement of upgrade/migration guidance and the remaining Kafka cleanup details.

[wenjin272]

I think we can remove the “Upgrades and migration” section from this guide. We plan to design compatibility for the Action State Store and Flink operator state in the next release. For now, the guide should describe current recovery requirements without implying broader upgrade compatibility. The existing 0.4 format change can go into release-specific migration notes.

[joeyutong]

Removed the general upgrade discussion and kept current recovery requirements in the recovery section. The known 0.4 format change now lives under Migration notes > Flink Agents 0.4 on the same page, keeping the Action State Store guidance together.

[wenjin272]

Sorry, my earlier wording was unclear. Please remove the 0.4 migration note from this guide. I’ll mention the breaking change in the release notes; we don’t need to provide a migration guide for the current 0.x releases. The removal of the general upgrade discussion looks good—thanks!

[joeyutong]

Removed the 0.4 migration note and updated the Deployment text and PR description accordingly.

[wenjin272]

Could we move the remaining “Checkpoint-aligned Kafka cleanup” subsection into the Consistency guide, including its prerequisites, topic policies, and CLI options? The cleanup procedure currently sends readers back to Configuration for these details. Keeping them together would make the procedure self-contained, while Configuration retains concise option descriptions and a link to the guide.

[joeyutong]

Moved the cleanup prerequisites, topic policies, and CLI options into Consistency. Configuration now keeps concise option descriptions and a direct link to the procedure.

[wenjin272]

LGTM once the conflicts are resolved.