From e5f797dee4d22c6cefa295636e0a72e883379eeb Mon Sep 17 00:00:00 2001
From: fi3ework <fi3ework@gmail.com>
Date: Fri, 15 May 2026 16:28:11 +0800
Subject: [PATCH 1/2] docs: add AGENTS.md with CLAUDE.md symlink

Documents repository conventions for AI coding agents: the assets-only
nature of the repo, the path-equals-URL deploy model via assets.rspack.rs,
naming conventions for logos / banners / OG images, and the mandatory
TinyPNG compression rule.

CLAUDE.md is a symlink to AGENTS.md so Claude Code picks it up too.
---
 AGENTS.md | 45 +++++++++++++++++++++++++++++++++++++++++++++
 CLAUDE.md |  1 +
 2 files changed, 46 insertions(+)
 create mode 100644 AGENTS.md
 create mode 120000 CLAUDE.md

diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..96e6987
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,45 @@
+# AGENTS.md
+
+## Repository nature
+
+This is an **assets-only repository** — brand and marketing visuals for the Rstack family (Rspack, Rsbuild, Rspress, Rsdoctor, Rslib, Rslint, Rstest). There is no source code, no `package.json`, no build / test / lint pipeline. Contributions are file additions, replacements, and renames.
+
+`cspell.json` is the only tooling config and exists solely to allowlist project names for spellcheckers run elsewhere.
+
+## Deploy model
+
+The repo is served verbatim via Cloudflare at `https://assets.rspack.rs/`. **The file path in the repo IS the URL path** — `rspack/rspack-logo.png` becomes `https://assets.rspack.rs/rspack/rspack-logo.png`. No build step rewrites paths, so renames and deletions are immediately user-visible (subject to the CDN's `max-age=14400` / 4h cache TTL).
+
+Implication: treat path changes as breaking. Prefer additive PRs over renames once a URL has been shared.
+
+## Layout convention
+
+Per-package top-level directories (`rspack/`, `rsbuild/`, `rspress/`, `rsdoctor/`, `rslib/`, `rslint/`, `rstest/`, plus `rstack/` for cross-family visuals and `web-infra/` for the parent org). Inside each:
+
+- **Root of the package dir** — primary, externally-linked deliverables (logo, banner, OG image, favicon, navbar logo).
+- **`<pkg>/assets/`** — ad-hoc / temporary media tied to a specific moment: blog post images, release-note illustrations, docs screenshots, profiling captures, animated demos (`.gif`, `.mp4`). Not a stable surface — files here may be added freely without the same naming rigor as the package root.
+- **`others/`** — source design files (`.sketch`) used to author multiple deliverables.
+
+## Naming conventions (load-bearing)
+
+- `<pkg>-logo[-WxH].{svg,png,ai,sketch,fig}` — primary brand mark; size suffix optional (`rsbuild-logo-512x512.png`).
+- `<pkg>-banner-v<MAJOR>-<MINOR>[-<PATCH>][-<PRE>].png` — **release announcement banners**. Use kebab-case for version dots: `v0-3`, `v1-0-alpha`, `v0-10-0`. (A few historical files use `vX.Y` with a literal dot — do not propagate that style.)
+- `<pkg>-og-image.png` — current OpenGraph card at the package root.
+- `navbar-logo-{dark,light}.png` — in-app navigation usage.
+- `favicon-<WxH>.png` — site favicons.
+
+When in doubt, grep the sibling packages (`rspack/`, `rsbuild/`) for precedent before inventing a new name — they have the most history.
+
+## Mandatory: TinyPNG before merge
+
+**Every added or updated PNG must be compressed via [TinyPNG](https://tinypng.com/) before the PR is merged.** This is enforced by the PR template checklist (`.github/PULL_REQUEST_TEMPLATE.md`) and is the single hard rule of the repo. Replacement-with-compressed-version PRs are routine and expected if a contributor forgets.
+
+## Workflow notes
+
+- `main` is the default branch; PRs go against `rstackjs/rstack-design-resources`.
+- Commit message convention from recent history: `chore(<pkg>): <imperative>` (e.g. `chore(rstest): add v0.10.0 banner`). Use `feat(<pkg>):` only for genuinely new asset families.
+- The repo has no CI checks beyond GitHub's defaults — review is human and visual.
+
+## License
+
+All assets are CC BY-NC-SA 4.0 (`CC-BY-NC-SA-4.0.md`). Non-commercial, share-alike, attribution required.
diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 120000
index 0000000..47dc3e3
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1 @@
+AGENTS.md
\ No newline at end of file

From 572e3f30188014602d272512e2d44566c0b2342c Mon Sep 17 00:00:00 2001
From: neverland <jait.chen@foxmail.com>
Date: Fri, 15 May 2026 21:06:38 +0800
Subject: [PATCH 2/2] Apply suggestion from @chenjiahan

---
 AGENTS.md | 3 ---
 1 file changed, 3 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index 96e6987..171f484 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -40,6 +40,3 @@ When in doubt, grep the sibling packages (`rspack/`, `rsbuild/`) for precedent b
 - Commit message convention from recent history: `chore(<pkg>): <imperative>` (e.g. `chore(rstest): add v0.10.0 banner`). Use `feat(<pkg>):` only for genuinely new asset families.
 - The repo has no CI checks beyond GitHub's defaults — review is human and visual.
 
-## License
-
-All assets are CC BY-NC-SA 4.0 (`CC-BY-NC-SA-4.0.md`). Non-commercial, share-alike, attribution required.