Sxnan opened a new issue, #779: URL: https://github.com/apache/flink-agents/issues/779
### Search before asking - [x] I searched in the [issues](https://github.com/apache/flink-agents/issues) and found nothing similar. ### Description Found during YAML doc verification (#742). Collection of doc-quality improvements for `docs/content/docs/development/yaml.md`: 1. **Inter-resource name references are not documented** — the example agent YAML wires up resources via name string fields: - `chat_model_setups[].connection` → name of a `chat_model_connections[]` entry - `chat_model_setups[].prompt` → name of a `prompts[]` entry - `chat_model_setups[].tools` → list of names from `tools[]` None of these cross-references are explicitly explained anywhere. A new user has to reverse-engineer them from the example. Add a short note (or a "References" column in the field tables) describing the lookup semantics. 2. **Class-alias table only covers chat-model** (lines 456-469) — the embedding-model and vector-store alias tables are abbreviated with "follow the same scheme". Materialize them. Bedrock has Java-only chat-model and embedding-model entries in `ResourceName.Java.BEDROCK_*` but no alias and no mention anywhere in the doc — Java users have no way to discover the FQN unless they grep the source. 3. **Schema re-export command is not documented** (lines 530-555) — the doc explains that `docs/yaml-schema.json` is the exported ground truth from the Pydantic specs, but never tells the reader how to regenerate it. The command is `python -m flink_agents.api.yaml.specs > docs/yaml-schema.json` (already referenced in `test_checked_in_schema_matches_pydantic_models`'s error message). Add it to the spec section. 4. **Cross-language section is one-directional** (lines 473-528) — the walkthrough only shows the Python loader consuming `type: java` resources. The symmetric case (Java loader consuming `type: python` resources) is supported but never mentioned, so Java users may not realize it works. Add a short note covering the reverse direction. ### Where to fix `docs/content/docs/development/yaml.md`. ### Version and environment Flink Agents 0.3.0 (`main`). ### Are you willing to submit a PR? - [ ] I'm willing to submit a PR! -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
