diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 333cf80c..2a6c0e29 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -145,6 +145,7 @@ To set up the project locally:
    ```
 
    _Note: `npm run format` currently targets CSS, HTML, Markdown, and Tailwind config files._
+   _Note: `npm run lint` checks for CSS errors, hex color usage (use tokens instead), inline styles, and design token compliance._
 
 5. **Git Hooks (Optional)**:
    We provide a script to set up a git pre-commit hook that runs linting and CSS builds automatically before you commit.
@@ -154,6 +155,16 @@ To set up the project locally:
 
 For a full guide, see the [Local Setup section in README.md](./README.md#local-setup).
 
+### Event Schema Validation
+
+When modifying event schemas or builders, verify your changes against the codebase and test suite:
+
+```bash
+node scripts/agent/validate-events.mjs
+```
+
+This script checks that all event builders produce valid events according to the definitions in `js/nostrEventSchemas.js`.
+
 ### Troubleshooting
 
 - **Browserslist Warning**: If you see `Browserslist: caniuse-lite is outdated` during the build, run:
diff --git a/README.md b/README.md
index 5f6631d3..77fe9d71 100644
--- a/README.md
+++ b/README.md
@@ -246,7 +246,7 @@ const event = buildVideoPostEvent({
     version: 3,
     title: "My First Video",
     videoRootId: "my-first-video", // Logical ID, matches the d-tag
-    url: "https://example.com/video.mp4",
+    url: "https://example.com/video.mp4", // The builder automatically derives the required 's' storage tag from this URL
     description: "This is a test video post sent via the SDK."
     // magnet: "magnet:?xt=urn:btih:..." // Optional fallback (provide the raw magnet string)
   }