docs(sdk): polish SDK docs + CI follow-ups from review (PR-only sync, links, usage_id)

[enyst]

Summary

• Fixes from roasted review and follow-ups on branch sdk
• Keep solutions minimal; no changes to MCP filter_tools_regex example

Key changes

1. CI/workflows

• sync-sdk-changes.yml: Stop mutating branches. Generate Agent SDK OpenAPI then create a branch and open a PR via peter-evans/create-pull-request. Added pull-requests: write permission and switched bot identity to openhands.dev.
• sync-docs-code-blocks.yml (already present on this branch): guarded triggers (main,sdk), no direct pushes; uses create-pull-request when content changes.

2. Sync script hardening

• .github/scripts/sync_code_blocks.py: No-op when agent-sdk path is not found (graceful), removed walrus operator in update path, simplified block replacement and comparison. Script no longer writes to GITHUB_OUTPUT; workflow owns outputs.

3. Docs information architecture

• docs.json: “Agent SDK (v1)” tab is primary for v1. Added an OpenAPI tab for Agent SDK pointing to openapi/agent-sdk.json. Left the legacy “OpenHands (Core) API)” tab in place for now; it can be removed when v0 is officially retired on sdk.

4. Broken links and consistency

• Replaced dead /sdk/architecture/* links with working destinations (or removed when no stable target existed yet). Example pages updated:
  • sdk/guides/hello-world.mdx
  • sdk/guides/custom-tools.mdx
  • sdk/guides/mcp.mdx
• Hello World import fixed to from openhands.sdk.preset.default import get_default_agent.
• LLM terminology unified to usage_id across the examples shown.

5. Domain migration

• Migrated external site links to openhands.dev where appropriate (company/blog/app/docs). Intentionally preserved docker., runtime., jira.* hosts.

Notes

• openapi/agent-sdk.json is not versioned in this branch; sdk target branch contains it and the dedicated sync workflow. The new OpenAPI tab will function post-merge.
• MCP examples (including filter_tools_regex) are unchanged per request.

Testing

• Basic link audit via grep; docs build expected to pick up both OpenAPI tabs once merged to sdk.

Request
Please review and merge into sdk (PR #32 source branch). This keeps CI non-destructive (PR-only), fixes broken links, and aligns SDK docs with v1 expectations.

@enyst can click here to continue refining the PR

[jamiechicago312]

Will review first thing tomorrow 👍

[enyst]

Thank you. They're actually to Xingyao's PR, so it's like, they're meant to be:

• either included in his PR
• or submitted to main, after his PR is merged in main.

[openhands-ai]

Looks like there are a few issues preventing this PR from being merged!

• GitHub Actions are failing:
  • Sync Documentation Code Blocks

If you'd like me to help, just leave a comment, like

@OpenHands please fix the failing actions on PR #33 at branch `pr/sync-openapi-prs`

Feel free to include any additional details that might help me get this PR into a better state.

_{^{You can manage your notification settings}}

[mamoodi]

Looks generally okay. I don't know what the sync job is for but wondering if it's just for SDK, it can just run when SDK changes or something.

Also can you run: mint broken-links
to make sure there's no broken links please. The API tabs will show up as broken links and that's a known issue in mintlify.

[enyst]

Yes, it’s a bit in flux. I think this PR or the other were trying to fix broken links.