Add shared architecture-docs submodule + CLAUDE.md#99
Merged
Conversation
Wires NaradaAI/architecture-docs as a git submodule at architecture-docs/ (relative URL, branch=main). Adds a top-level CLAUDE.md pointing at the shared docs with python-sdk.md emphasized, and a small GitHub Actions workflow that fails when the submodule pointer falls behind architecture-docs/main. The freshness check uses ARCHITECTURE_DOCS_READ_PAT (needs to be added as a repo secret with read access to NaradaAI/architecture-docs). Until the secret is configured, the check emits a warning annotation and exits 0 so this PR can land cleanly. Note: this repo is public, so PRs from forks won't have access to the secret — graceful-degrade ensures those PRs still pass.
![github-advanced-security[bot]](https://avatars.githubusercontent.com/in/57789?s=60&v=4){kind=small}
This reverts commit 606e597.
zizhengtai
approved these changes
May 1, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Wires the new
NaradaAI/architecture-docsrepo (merged in PR #1) intonarada-python-sdkas a git submodule atarchitecture-docs/. This is one of three sibling consumer PRs (also opened incaddieandfrontend).Pinned at architecture-docs commit
d2a82e1c(mainHEAD as of this PR update).What's in this PR
.gitmodules(new) — first submodule entry:architecture-docs→../architecture-docs.git, tracking branchmain. Relative URL pattern works for SSH and HTTPS parent clones.architecture-docs/— gitlink (mode 160000) pinning the submodule.CLAUDE.md(new) — top-level project context for AI coding agents, including a bootstrap command for fresh clones before linking to shared docs.python-sdk.mdis emphasized as the most relevant doc for this repo..github/workflows/architecture-docs-freshness.yml(new) — compares the pinned gitlink againstarchitecture-docs/main, with explicitcontents: readpermissions.No source code touched. Pure config + docs.
Note on this repo being PUBLIC
Fork PRs and Dependabot PRs may not receive normal Actions secrets under the
pull_requesttrigger, so those runs emit an explicit warning and skip freshness enforcement. If we want enforcement for those sources too, we should move this check to a carefully scopedpull_request_targetor equivalent trusted workflow that never checks out or executes untrusted PR code.Freshness check behavior
The workflow uses
${{ secrets.ARCHITECTURE_DOCS_READ_PAT }}(a fine-grained PAT with read access toNaradaAI/architecture-docs) when available. If the secret is absent, the job emits an explicit warning and exits 0, so this PR can land before repo secrets are configured.This means freshness is enforced only on runs that receive
ARCHITECTURE_DOCS_READ_PAT.Follow-up needed after merge
Add
ARCHITECTURE_DOCS_READ_PATto this repo's Actions secrets to enable freshness enforcement.Test plan
origin/main— clean isolation from any in-flight working branchesgit -C architecture-docs rev-parse HEADmatchesd2a82e1c76af3e702a13cd760f39af02bdf2bc0e.gitmodulesparses cleanlygit diff --checkgit submodule update --init architecture-docspath succeeds locally with an authenticated GitHub tokenarchitecture-docs/main