docs: add automated upstream sync workflow

[divyasinghds]

Summary

• Adds a Claude-powered workflow that keeps five docs pages in sync with their upstream READMEs.
• Source repos fire repository_dispatch on push → this repo fetches the upstream file → Claude rewrites the target .mdx in docs voice → a PR is opened/updated on docs/sync-upstream.
• Daily 06:00 UTC cron + manual workflow_dispatch as safety nets.

Mapping

Source	Docs page
tracebloc/tracebloc-py-package README.md	tools-help/tracebloc-package.mdx
tracebloc/client README.md	environment-setup/setup-guide.mdx
tracebloc/start-training README.md	join-use-case/start-training.mdx
tracebloc/data-ingestors Readme.md	create-use-case/prepare-dataset.mdx
tracebloc/model-zoo README.md	create-use-case/templates.mdx

Files

• .github/sync-sources.yml — mapping (extend by appending entries)
• .github/workflows/sync-docs.yml — sync job
• .github/notify-docs.workflow-template.yml — template to copy into each source repo

Required setup before this works

1. Org secret DOCS_DISPATCH_TOKEN — fine-grained PAT scoped to tracebloc/docs, Contents: Read and write. Lets source repos fire dispatch.
2. Repo secret SOURCE_REPOS_TOKEN on this repo — fine-grained PAT scoped to tracebloc/tracebloc-py-package, Contents: Read-only. Needed because that repo is private.
3. ANTHROPIC_API_KEY — assumed already org-wide.
4. Copy .github/notify-docs.workflow-template.yml into each source repo as .github/workflows/notify-docs.yml, replacing <SOURCE_ID> with the matching id from sync-sources.yml. For data-ingestors, also change paths: to Readme.md.

Test plan

• Add DOCS_DISPATCH_TOKEN org secret and SOURCE_REPOS_TOKEN repo secret.
• Merge this PR.
• Run Actions → Sync docs from upstream → Run workflow with empty source_id. Verify the resulting PR's edits against current upstream READMEs.
• Add notify-docs.yml to one source repo (e.g. tracebloc/client), push a README change, confirm dispatch fires this workflow.
• Roll out notify-docs.yml to remaining source repos.

🤖 Generated with Claude Code

---

Note

Medium Risk
Medium risk because it introduces a scheduled/dispatch-triggered workflow that fetches external repo contents, invokes an LLM to rewrite docs, and pushes changes via automated PRs using repo/org secrets.

Overview
Adds an automated GitHub Actions pipeline (.github/workflows/sync-docs.yml) that, on repository_dispatch, manual trigger, or daily schedule, fetches upstream README files and uses anthropics/claude-code-action to update specific docs pages, then opens/updates a PR on docs/sync-upstream.

Introduces a central mapping file (.github/sync-sources.yml) defining the upstream repo/ref/path → docs dest targets plus per-source rewrite instructions, and a reusable upstream workflow template (.github/notify-docs.workflow-template.yml) for source repos to trigger this repo via repository_dispatch with a source_id payload.

^{Reviewed by Cursor Bugbot for commit 5065236. Bugbot is set up for automated code reviews on this repo. Configure here.}

[cursor]

Cursor Bugbot has reviewed your changes and found 2 potential issues.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 5065236. Configure here.}

[cursor]

API key passed via env instead of action input

High Severity

The ANTHROPIC_API_KEY is passed as a step-level env: variable, but anthropics/claude-code-action@v1 expects it as a with: input named anthropic_api_key. The action reads inputs via core.getInput(), which looks for INPUT_ANTHROPIC_API_KEY, not the raw ANTHROPIC_API_KEY environment variable. This mismatch will likely cause the Claude step to fail authentication, breaking the entire sync workflow.

 

^{Reviewed by Cursor Bugbot for commit 5065236. Configure here.}

[cursor]

Temporary .sync-cache/ directory committed to PR

Medium Severity

The fetch step creates .sync-cache/ with raw upstream README content inside the git working directory. The peter-evans/create-pull-request@v6 step has no add-paths restriction, so it defaults to staging all new and modified files. Since the repo has no .gitignore, the .sync-cache/ directory and its files will be committed to the PR alongside the intended docs changes. This also means a PR is created/updated on every cron run even when Claude makes no docs edits, since the cache files always appear as new untracked files.

Additional Locations (1)

• .github/workflows/sync-docs.yml#L61-L73

 

^{Reviewed by Cursor Bugbot for commit 5065236. Configure here.}