[hotfix][docs] Add module-level AGENTS.md guides and fix stale root claims

[Vamsi-klu]

What is the purpose of the change

Continue FLINK-39477 item 3: module-level AGENTS.md guides for the modules agents actually edit, plus two stale claims in the root AGENTS.md.

Related PRs:

• apache/flink#27776 landed the original root AGENTS.md and AI disclosure
• Vamsi-klu/flink#1 was the stale fork-only copy (closed, 370 commits behind)

This branch is rebased onto current apache/flink master. The Cursor GitHub App cannot open PRs on apache/flink. Open the real review PR as Vamsi-klu:

https://github.com/apache/flink/compare/master...Vamsi-klu:flink:cursor/agents-md-guides-4436?expand=1

This fork PR is only a holding copy of that branch.

Codex review 4996867308 is addressed in 6be96e7000f: application-mode main() can run on the JobManager, and REST docs regenerate via -Dgenerate-rest-docs.

Brief change log

• Add AGENTS.md for flink-core, flink-runtime, flink-streaming-java, flink-clients, flink-table-common, flink-table-api-java, flink-connector-base, and flink-statebackend-rocksdb
• Document that the DataStream API, operator/task base classes, and StreamGraph live in flink-runtime (org.apache.flink.streaming.*) after FLINK-36063
• Fix the root Checkstyle note: every module inherits maven-checkstyle-plugin in validate with failOnViolation=true. flink-core and flink-runtime only override their suppressions file. flink-optimizer is not a module here
• Add a "Module-specific agent guides" index to the root AGENTS.md
• Qualify JobManager / application-mode wording so agents do not treat main() as client-only
• Point REST handler changes at ./mvnw package -Dgenerate-rest-docs and the real shortcode/OpenAPI output paths

Verifying this change

Documentation only. Checked against current master:

• DataStream.java is in flink-runtime, not flink-streaming-java
• flink-core and flink-runtime poms override suppressionsLocation only
• Dispatcher.maybeSubmitApplicationInApplicationMode() and PackagedProgramApplication run the user entry point on the JobManager in application mode
• flink-docs generate-rest-docs profile writes docs/layouts/shortcodes/generated/rest_v1_dispatcher.html and docs/static/generated/rest_v1_dispatcher.yml
• License headers match the existing planner/runtime AGENTS.md files

Does this pull request potentially affect one of the following parts:

• Dependencies (does it add or upgrade a dependency): no
• The public API, i.e., is any changed class annotated with @Public(Evolving): no
• The serializers: no
• The runtime per-record code paths (performance sensitive): no
• Anything that affects deployment or recovery: JobManager (and its components), Checkpointing, Kubernetes/Yarn, ZooKeeper: no
• The S3 file system connector: no

Documentation

• Does this pull request introduce a new feature? no
• If yes, how is the feature documented? not applicable

---

Was generative AI tooling used to co-author this PR?

• Yes (please specify the tool below)

Generated-by: Claude Code (Claude Opus 4.8); Cursor Grok 4.6 (rebase onto current master and Codex review fixes)

  

[cursor]

cc @MartijnVisser @snuyanzin @gustavodemorais @raminqaf

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 28cb7c6cb7

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".