feat(docs-site): scaffold cougr-site repo with mdBook IA and content-sync from the core repo

[salazarsebas]

Part of #239

Background

No documentation site infrastructure exists. Per the repository strategy, the site lives in a cougr-site/ folder within this repository, kept separate from the crate root so it has its own build/deploy path, but it must not fork the content: docs/*.md in this repository remains the single source of truth, and cougr-site/ builds from it (via a sync step) rather than duplicating it by hand.

Objective

Build out a cougr-site/ folder in this repository with an mdBook skeleton implementing the 6-section information architecture from docs/strategy/12-documentation-architecture.md, and a working, documented mechanism that syncs docs/*.md content from this repository into cougr-site/src/ at build time (or on a defined schedule), without manual copy-paste.

References

• Full IA specification: docs/strategy/12-documentation-architecture.md
• mdBook configuration reference: https://rust-lang.github.io/mdBook/format/configuration/general.html
• mdBook SUMMARY.md structure: https://rust-lang.github.io/mdBook/format/summary.html
• Repository strategy rationale: docs/strategy/10-repository-strategy.md

In scope

1. cougr-site/ folder in this repository, mdBook-based, with SUMMARY.md structured into the 6 sections: Start, Learn, Reference, Showcase, Design, Community.
2. A sync step (a script or GitHub Action step) that reads the current docs/*.md, ARCHITECTURE.md, CHANGELOG.md, and docs/adr/*.md from this same repository's checkout and places them into the correct mdBook section, with front-matter/path rewriting as needed for mdBook's expectations. This must read the local checkout directly — it must not clone the repository over the network, since site and source now live in the same working tree.
3. A documented decision on sync cadence and trigger (e.g. run on every push touching docs/** or cougr-site/**) — pick one, document why, and implement it.
4. Placeholder pages for content not yet written (tutorial, boundary guide, etc., tracked in sibling sub-issues) so the site's navigation is complete even before every page has real content.
5. Local build instructions in cougr-site/README.md.

Out of scope

• The actual tutorial/pattern-guide content (separate sub-issues).
• The showcase gallery generator (separate epic); this issue only reserves its place in the navigation.
• Custom domain setup; a default GitHub Pages URL is sufficient for v1.

Definition of done

• cougr-site/ exists in this repository, builds locally with mdbook build and mdbook serve.
• Running the sync step against the current checkout produces an accurate, current copy of docs/*.md content in the site, without a network clone.
• Site navigation matches the 6-section IA with no broken internal links.

[Damilorlar]

@Damilorlar has applied to work on this issue as part of the Stellar Wave Program's 7th wave.

I would love to work on this project, dear maintainer.

ℹ️ Repo Maintainers: To accept this application, review their application or assign @Damilorlar to this issue.

[Chigybillionz]

@Chigybillionz has applied to work on this issue as part of the Stellar Wave Program's 7th wave.

i am active to take on this

ℹ️ Repo Maintainers: To accept this application, review their application or assign @Chigybillionz to this issue.

[khaylebfortune]

@khaylebfortune has applied to work on this issue as part of the Stellar Wave Program's 7th wave.

Hello Maintainer, I can fix this issue.

ℹ️ Repo Maintainers: To accept this application, review their application or assign @khaylebfortune to this issue.

[Danielobito009]

@Danielobito009 has applied to work on this issue as part of the Stellar Wave Program's 7th wave.

I would like to work on this project, please assign to me

ℹ️ Repo Maintainers: To accept this application, review their application or assign @Danielobito009 to this issue.

[ayo-ola0710]

@ayo-ola0710 has applied to work on this issue as part of the Stellar Wave Program's 7th wave.

Hi I will love to handle these issue pls

ℹ️ Repo Maintainers: To accept this application, review their application or assign @ayo-ola0710 to this issue.

[Spagero763]

@Spagero763 has applied to work on this issue as part of the Stellar Wave Program's 7th wave.

I would like to take up this issue

ℹ️ Repo Maintainers: To accept this application, review their application or assign @Spagero763 to this issue.

[drips-wave]

Congratulations, @ayo-ola0710! 🎉 Your application was accepted by the repo's maintainers, and the issue is due on July 30, 2026.

🧑‍💻 @ayo-ola0710: Please resolve the issue such that the repo's maintainers have enough time to review your contribution before the due date. You'll earn Points for completing the issue on-time, which will make you eligible for a share of the Stellar Wave Program's reward pool.

Warning

When opening a PR, please link it to this issue to ensure it gets tracked accurately. Points are awarded when this issue is marked as completed by the maintainer.

🤠 Repo maintainers: Please keep an eye on the contributor's progress and review their work before the due date. You can manage this issue, including adjusting its complexity and points, here.

🌊 Happy Wave 🌊