feat(docs): generate Commands section of README from cobra metadata

[ewanharris]

Description

What problem is being solved?

The Commands section of README.md was hand-rolled and had drifted out of sync with the actual CLI — commands were missing, examples were outdated, and there was no mechanism to catch regressions.

How is it being solved?

A code generator (cmd/gendocs) walks the cobra command tree and splices a fresh Commands section and table-of-contents block into README.md. Command descriptions, parameters, examples, and response samples are sourced directly from each command's Long, Example, and Annotations fields, making the cobra definition the single source of truth.

A make generate-docs target runs the generator, and a new CI step fails the build if the committed README doesn't match the generated output, so drift is caught on every PR.

What changes are made to solve it?

• internal/doc: new package containing the generator and splice logic, with tests
• cmd/gendocs/main.go: entrypoint that wires the root command into the generator
• Makefile: generate-docs target
• .github/workflows/main.yaml: Check README commands section is up to date CI step
• Long, Example, and docs:response / docs:response:lang annotation fields added to all store, model, tuple, and query commands to populate the generated output
• README.md: Commands section and ToC block wrapped with splice markers; content regenerated

One change from this is that commands are now ordered alphabetically (cobra's Commands() order), so the generated section reads Authorization Models -> Manage JSON-to-tuple mappings -> Relationship Queries -> Stores -> Relationship Tuples rather than the previous hand-written order that kind of followed the natural flow of usage. Top-level runnables (version) are excluded from both the body and the ToC as they have no group heading.

References

This is inspired by similar functionality in auth0-cli that is used to build the website for it.

Review Checklist

• I have clicked on "allow edits by maintainers".
• I have added documentation for new/changed functionality in this PR or in a PR to openfga.dev [Provide a link to any relevant PRs in the references section above]
• The correct base branch is being used, if not main
• I have added tests to validate that the change in functionality is working as expected

[coderabbitai]

Important

Draft PR not reviewed

Draft PRs are not automatically reviewed by default.

• Trigger a manual review

To automatically review draft PRs, update your CodeRabbit configuration:

reviews:
  auto_review:
    drafts: true

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}