1
# AI Collaboration Reference: Agent Reference Manual
2

3
If you are using an AI coding assistant (such as GitHub Copilot, Cursor, Gemini Antigravity, or a custom Agent) to help you modify this blog project, you can direct the AI to read this chapter and its sub-pages.
4

5
This guide encapsulates the deep design constraints of this blog (which is heavily customized from Fuwari), allowing AI assistants to quickly understand the project architecture and significantly reducing the chance of post-modification errors or incorrect changes.
6

7
## Guide Directory
8

9
This guide is modularized into the following sub-articles. It is recommended to feed them to the AI assistant based on the task:
10

11
1. **[Docs & Category Tree](./01-docs-system/)**: Documentation physical directory mapping, ordering rules, and sorting conflict mechanisms.
12
2. **[Persistent BGM](./02-bgm-system/)**: Persistent background music player implementation and playlist configurations.
13
3. **[Theme & CSS](./03-theme-system/)**: Tailwind CSS configuration, OKLCH color space usage, and global style variables mapping.
14
4. **[i18n & Fallback](./04-i18n-system/)**: Differences between content i18n and UI i18n, automatic i18n prefix injection plugins, and safety fallback recovery mechanisms.
15
5. **[MDX & Hydration](./05-mdx-hydration/)**: Hydration directives and instructions for framework components embedded in markdown documents.
16
6. **[Swup & Boundaries](./06-swup-routing/)**: Page transition architecture, sidebar partial sync mechanism, mobile scrolling positioning order, and language selection Swup bypass.
17
7. **[Custom Plugins](./07-custom-plugins/)**: Guidelines for custom build-time plugins in the `src/astro-plugins/` directory.
18
8. **[Troubleshooting](./08-troubleshooting/)**: Error diagnostics, reference resources path, and fallback procedures.
19

20
## Mandatory Prompt Addendum for Long-form MDX
21

22
When assigning an AI assistant to create or modify a long post, append the following requirements to the task prompt:
23

24
- Treat Safari/WebKit scrolling performance as a release requirement.
25
- Do not apply transitions to all descendants of article content.
26
- Keep Posts and Docs on native body scrolling; do not add body-level custom scrollbar initialization.
27
- Use `client:visible` for below-the-fold interactive components and avoid batches of `client:only` or `client:load`.
28
- Batch TOC and scroll-linked UI work with `requestAnimationFrame`, and skip updates when state is unchanged.
29
- Do not use `content-visibility` around Astro islands without proving that visibility-triggered hydration still works.
30
- Run `pnpm build`, then verify scrolling, anchor navigation, TOC tracking, theme switching, Swup navigation, and hydration on the long-form regression fixture.