docs: weekly architecture docs refresh automation

[enyst]

This PR adds a weekly workflow that refreshes the SDK architecture documentation using the OpenHands Cloud API, adapted from the ideas in OpenHands/OpenHands#10566.

What’s included

• .github/workflows/weekly-architecture-refresh.yml
  • Runs weekly (Mon 07:00 UTC) and via manual dispatch
  • Calls a minimal helper to start an OpenHands conversation with a focused prompt
  • The remote agent opens a PR itself if updates are needed
• scripts/openhands_api.py
  • Minimal Python client for the OpenHands API (POST /api/conversations)
  • Reads OPENHANDS_API_KEY from repo/org secrets
• scripts/prompts/architecture_refresh.j2
  • Clear instructions for auditing and updating sdk/arch pages in the docs repo
  • Includes style and factuality requirements:
    • Do not invent behavior; verify every statement against repository code or existing docs.
    • Cite sources inline with file paths and short context (e.g., (source: openhands/agent_server/conversation.py)).
    • Prefer Mermaid diagrams; keep tone clear and neutral.
    • Include Last updated timestamp and Source commit at the bottom of each page.
  • Pull Request requirements:
    • If proposing changes vs previous week, open a PR titled: "docs: weekly architecture docs refresh"
    • Follow .github/pull_request_template.md; run pre-commit; ensure CI passes
  • Event Stream special note: requires a section "Event Stream Subscription Mechanism" with a real-world example

Credentials

• The workflow expects OPENHANDS_API_KEY to be set as an Actions secret. If a different secret name is preferred (e.g., ALL_HANDS_BOT), we can adjust the workflow environment variable.

Notes

• This PR intentionally does not re-add an OpenAPI sync job (already present in this repo).
• The helper defaults to https://app.all-hands.dev and simply prints the conversation URL for traceability.

Co-authored-by: openhands [email protected]

@enyst can click here to continue refining the PR

[neubig]

Thanks for this @enyst ! But is there a reason why we need openhands_api.py and couldn't just use the more standard workflow here? https://github.com/OpenHands/software-agent-sdk/tree/main/examples/03_github_workflows/01_basic_action

If there's a reason why you particularly want to run this on the cloud, it might be nice to have a standard "dispatch to cloud" github workflow in the examples directory, and then re-use that here.

[neubig]

Converting to draft for now pending review comments.