Snippets Assets Policy

Governance rules for snippets/assets/ — what may be added, size limits, current canonical directories, and transition-state constraints.

Snippets Assets Policy

Defines what may be added to snippets/assets/, how assets are organised, and when they may be removed.

---

Scope

In scope	Out of scope
All files under snippets/assets/	snippets/components/ (JSX component library)
Image, SVG, data, and script assets	snippets/data/ (structured JSON/JS data)
docs.json logo and favicon references	api/ spec files

---

Rules

1. Reference required before merge — no asset may be added to snippets/assets/ without a verified reference in at least one of: v1/, v2/, snippets/, or docs.json. Unreferenced assets will be removed during audits.

2. Size limit: 2 MB per image file — images over 2 MB must be optimised before commit. PNG files over 500 KB should be reviewed for WebP conversion. The only exceptions are generated OG images in media/og-images/.

3. No duplicate files across canonical subdirectories — canonical directory wins and duplicate copies should be removed during the owning migration. Current canonical subdirectories:

   • logos/ — shared logo assets, including the favicon bundle in logos/favicon/
   • media/ — shared raster/video assets, including media/og-images/ and media/images/site/
   • domain/ — legacy assets under audit only; no new permanent additions
   • data/ — non-image data assets
   • scripts/n8n/ — workflow docs pending relocation out of assets

4. No backup files — .bak, .backup, or similarly named files are not permitted. Use git history for rollback.

5. No new files under the removed site/ bucket — site/ has been dissolved. New favicon assets go to logos/favicon/, new generated OG artifacts go to media/og-images/, and new site-specific images go to media/images/site/.

6. domain/ is frozen pending phase-two audit — do not add new assets under domain/ unless the work is explicitly part of the approved domain migration. Existing domain assets must be classified as MOVE or ARCHIVE before relocation.

7. No ad-hoc subdirectories — new subdirectories under snippets/assets/ require a policy update to this document. Use the existing subdirectories.

---

Canonical Directory Map

snippets/assets canonical directory map

snippets/assets/
├── logos/
│   ├── favicon/   ← canonical multi-format favicon bundle
│   ├── Arbitrum/
│   └── products/
├── media/
│   ├── heros/
│   ├── images/
│   │   ├── showcase/
│   │   └── site/   ← current site-scoped images
│   ├── og-images/  ← canonical generated OG images per locale
│   └── videos/
├── domain/        ← legacy assets under audit; phase-two migration pending
│   ├── 00_HOME/
│   ├── 01_ABOUT/
│   ├── 02_COMMUNITY/
│   ├── 04_GATEWAYS/
│   ├── 10_PRODUCTS/
│   └── SHARED/
├── data/          ← non-image data assets
└── scripts/n8n/   ← n8n workflow documentation pending relocation

---

Enforcement

Mechanism	Trigger	Action
Manual audit	Governance cleanup phases	Grep for unreferenced assets; delete after 30-day notice
Pre-commit hook	File deletion guard	Requires allow-deletions=true trailer for asset deletions
PR review	Any new asset added	Reviewer confirms reference exists before merging

---

Transition Status (2026-04-04)

Phase	Status	Notes
/site migration	complete	logos/favicon/, media/og-images/, and media/images/site/ are canonical
root sitemap-ai.xml consolidation	complete	snippets/assets/site/sitemap-ai.xml removed; repo root remains canonical
/domain migration	pending audit	use snippets/_workspace/audit.md as the phase-two planning surface

---

Related

• Docs Guide Structure Policy
• Root Allowlist Governance
• Workspace Lifecycle Policy