docs: split SITE-ARCHITECTURE.md into on-demand reference modules

[yonib05]

Description

Splits site/SITE-ARCHITECTURE.md (926 lines) into on-demand reference modules so agents and contributors load only the subsystem they are working on, instead of the whole file as ambient context.

What stays in SITE-ARCHITECTURE.md (408 lines): the overview, Key Customizations (sidebar, route middleware, snippets plugin, link resolution, @api shorthand), astro.config.mjs details, custom component implementations, temporary migration files, blog, and dependency pinning, plus a table of the new modules.

Moved to new focused modules under site/reference/:

Old section	New file
Python API Reference Generation	site/reference/python-api-generation.md
TypeScript API Reference Generation	site/reference/typescript-api-generation.md
Custom Landing Page + Testimonials Content Collection	site/reference/landing-page.md
URL Redirects	site/reference/url-redirects.md
LLM-Friendly Documentation (llms.txt)	site/reference/llms-txt.md

Content moves verbatim, with a short header on each module pointing back to the overview.

Deduplicated against .agents/references/mdx-authoring.md: the Custom Frontmatter Fields and MDX Components sections largely restated mdx-authoring.md, so they are removed from SITE-ARCHITECTURE.md in favor of links. Unique bits are merged into mdx-authoring.md: the Sidebar Badges frontmatter pattern, the exact banner texts rendered by languages/community/experimental, and the "neither Syntax nor Tabs" guidance for conceptual SDK differences. The MkDocs Snippets Plugin entry keeps its implementation notes (what/why) and links to mdx-authoring.md for syntax.

Directory choice: .agents/references/ holds cross-cutting agent authoring references (voice, terminology, MDX patterns, code verification) consumed by the docs skills. These five modules are site implementation deep-dives, not authoring guidance, so they live next to SITE-ARCHITECTURE.md as site/reference/*.md, mirroring how SITE-ARCHITECTURE.md itself sits in site/. Happy to move them under .agents/references/ instead if you prefer one bucket.

Inbound references updated: site/CONTRIBUTING.md now points frontmatter/MDX topics at mdx-authoring.md and API doc generation at the two new modules. site/AGENTS.md L385 links to the moved #custom-frontmatter-fields anchor, but that line is inside the block a parallel PR is replacing with a pointer to mdx-authoring.md, so it is intentionally not touched here to avoid conflicts.

Opening as a draft since the split boundaries are judgment calls worth shaping in review.

Related Issues

N/A

Documentation PR

This PR is itself a documentation restructure under site/ and .agents/.

Type of Change

Documentation update

Testing

Docs-only change, no runtime surface. Verified link integrity by grepping the repo for SITE-ARCHITECTURE and section anchors, and spot-checking that every moved section's content exists verbatim in exactly one new file.

• I ran hatch run prepare

Checklist

• I have read the CONTRIBUTING document
• I have reviewed and understand every line of code in this PR, including any generated by AI tools, and I can explain why it works
• My change is focused and reasonably small; I have split unrelated work into separate PRs
• I have added any necessary tests that prove my fix is effective or my feature works
• I have updated the documentation accordingly
• I have added an appropriate example to the documentation to outline the feature, or no new docs are needed
• My changes generate no new warnings
• Any dependent changes have been merged and published

---

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.

[github-actions]

Issue: site/AGENTS.md:385 links to SITE-ARCHITECTURE.md#custom-frontmatter-fields, but this PR removes the "Custom Frontmatter Fields" section from SITE-ARCHITECTURE.md (moved to mdx-authoring.md). That anchor is now dangling. The PR description notes this is intentionally deferred to a parallel PR to avoid conflicts — the risk is that if the parallel PR slips or is abandoned, main ships a broken link.

Suggestion: Since it's a one-line, non-conflicting edit (only the #anchor fragment/target changes), consider repointing it to ../.agents/references/mdx-authoring.md in this PR. If you'd rather keep the boundary clean, please confirm the parallel PR is queued ahead of this one, or track it so the broken link doesn't linger on main.

[github-actions]

Issue: The new site/reference/ directory (5 files) isn't reflected in the Directory Structure block in site/AGENTS.md. That file carries an explicit rule: "After making changes that affect the directory structure (adding new directories, moving files, or adding significant new files), you MUST update this directory structure section." Adding a new top-level reference/ directory qualifies.

Suggestion: Add a reference/ entry to the tree in site/AGENTS.md (near the SITE-ARCHITECTURE.md line), e.g. ├── reference/ # On-demand site-architecture deep-dives. Optionally add a short bullet in the "Directory Purposes" section describing what lives there.

[github-actions]

Assessment: Comment (nearly ready — two link/consistency follow-ups)

Clean, well-scoped restructure. I verified the moved sections landed verbatim (with headings correctly promoted for standalone files), the remaining SITE-ARCHITECTURE.md is coherent at 408 lines with a good module index, back-links resolve, and the mdx-authoring.md dedup is tidy. The two open items are both about keeping cross-file links honest, not content.

Review Categories

• Docs consistency: New site/reference/ directory not reflected in site/AGENTS.md's Directory Structure block, which the file's own rule requires when adding directories.
• Link integrity: One dangling anchor (site/AGENTS.md:385 → #custom-frontmatter-fields) is knowingly deferred to a parallel PR; worth resolving here or tracking so it doesn't land on main. All other moved-content links and anchors check out.

The split boundaries and on-demand module approach read well — thanks for the clear PR write-up making the judgment calls easy to review.

[yonib05]

Both addressed in 0917f7c: added reference/ to the directory tree (plus a line in Integration with Other Files), and repointed the AGENTS.md:385 link to mdx-authoring.md#frontmatter-schema so no dangling anchor lands on main regardless of PR ordering. Note: #3288 deletes that whole section of site/AGENTS.md; whichever merges second will need a trivial rebase, and the link fix here is subsumed by #3288 if it goes first.

[github-actions]

Assessment: Approve ✅

Confirmed both follow-ups are resolved in 0917f7c:

• Directory structure: reference/ now appears in the tree (site/AGENTS.md:63) with a matching entry in Directory Purposes (:207). Satisfies the file's own update rule.
• Dangling anchor: site/AGENTS.md:387 now points at ../.agents/references/mdx-authoring.md#frontmatter-schema; I verified the target section (## Frontmatter Schema) exists in mdx-authoring.md, so the link resolves regardless of how docs(site): replace duplicated examples guide with reference pointer #3288 sequences. Good call making it non-order-dependent.

Content integrity was already verified as verbatim. Nothing else blocking — nice, clean restructure. Thanks for the quick turnaround.

[github-actions]

Documentation Preview Ready

Your documentation preview has been successfully deployed!

Preview URL: https://d3ehv1nix5p99z.cloudfront.net/pr-cms-3295/docs/user-guide/quickstart/overview/

Updated at: 2026-07-16T20:25:41.779Z

[zastrowm]

What's driving these changes?

[yonib05]

What's driving these changes?

I am testing a skill to work on strandly that will keep the repos clean of bloat that will periodically review the site and look for simplifications, duplicate content, and overall best practices for both LLMs and code.

[github-actions]

Re-reviewed after the main merge (2b6d525) — all clean, approval stands ✅

• reference/ remains in the directory tree and Directory Purposes in site/AGENTS.md.
• The frontmatter link still resolves to mdx-authoring.md#frontmatter-schema (target ## Frontmatter Schema intact).
• No dangling SITE-ARCHITECTURE.md# anchors repo-wide, no merge-conflict markers, and CONTRIBUTING.md's links to the new modules are valid.

Nothing new to address — good to merge once #3288 sequencing is settled.

[zastrowm]

I am testing a skill to work on strandly that will keep the repos clean of bloat that will periodically review the site and look for simplifications, duplicate content, and overall best practices for both LLMs and code.

I'm semi concerned that we're going to have a lot of needless PRs - like continuous improvement is good, but I'd like to dedicate resources to things that we've identified as needs or useful?

[yonib05]

I am testing a skill to work on strandly that will keep the repos clean of bloat that will periodically review the site and look for simplifications, duplicate content, and overall best practices for both LLMs and code.

I'm semi concerned that we're going to have a lot of needless PRs - like continuous improvement is good, but I'd like to dedicate resources to things that we've identified as needs or useful?

Fair point, I suppose not doing it automatically. To be clear, this wave is not representative of what it would look like ongoing. But I can see this being subjective somewhat, I did close some that I didn't think were practically useful.