Update AGENTS.md (+1 more changes)

AGENTS.md

@@ -3,7 +3,7 @@
 ## Commands
 
 - **Dev server**: `pnpm dev` (requires Ruby for markdown caching)
-- **Build**: `pnpm build` (runs `cache_markdown` + Astro build)
+- **Build**: `pnpm build`
 - **Test**: `pnpm test` (runs Vitest in watch mode)
 - **Run single test**: `pnpm vitest run <file-path>` or `pnpm vitest <file-path>` (watch mode)
 - **All tests (CI)**: `pnpm ci` (runs all linters, tests, and build)
@@ -15,8 +15,11 @@
 - **Package manager**: pnpm (v8.15.4+)
 - **Framework**: Astro with TypeScript (strict mode), Tailwind CSS
 - **Imports**: Use `~/` alias for `src/` directory; Prettier organizes imports automatically
-- **Formatting**: No semicolons, single quotes, no trailing commas (see `.prettierrc`)
 - **Types**: Use Zod schemas for runtime validation (see `SheetFrontmatter.ts`); TypeScript strict mode enabled
 - **Naming**: camelCase for variables/functions, PascalCase for components/types
 - **Error handling**: Distinguish operational (expected) vs unexpected errors; return error objects for operational errors
 - **Testing**: Vitest with globals enabled; use `it.each()` for repeated test cases; prefer object constants over helper functions
+
+## Markdown files
+
+Consult @_docs/writing-guidelines.md for formatting *.md files.

_docs/writing-guidelines.md

@@ -43,21 +43,52 @@ H3 content length:
 4. **Quick reference**: Dense information for experienced developers
 5. **Learning path**: Logical progression for newcomers
 
-## Examples
+## H3 writing guidelines
 
-- Place documentation links in the end.
-- Prefer to write explanations *after* a pre/table.
+- Place documentation links in the end. (see next for example)
+- Prefer to write explanations *after* a pre/table. Example:
 
-````markdonw
-### Setting default props
+  ````markdown
+  ### Setting default props
   
-```jsx
-Hello.defaultProps = {
+  ```jsx
+  Hello.defaultProps = {
     color: 'blue'
-}
-```
+  }
+  ```
   
-Default properties are used if no properties are given.
+  Default properties are used if no properties are given.
   
-See: [defaultProps](https://reactjs.org/docs/react-component.html#defaultprops)
-````
+  See: [defaultProps](https://reactjs.org/docs/react-component.html#defaultprops)
+  ````
+
+- When an example has multiple files, use H4 as filename markers. Example:
+
+  ````markdown
+  ### via Data Attributes
+  
+  #### index.html.erb
+  
+  ```html
+  <a
+    href="#"
+    data-reflex="click->CounterReflex#increment"
+    data-step="1"
+    data-count="<%= @count.to_i %>"
+    >Increment <%= @count.to_i %></a
+  >
+  ```
+  
+  #### counter_reflex.rb
+  
+  ```ruby
+  class CounterReflex < StimulusReflex::Reflex
+    def increment
+      @count = element.dataset[:count].to_i + element.dataset[:step].to_i
+    end
+  end
+  ```
+  
+  Trigger reflexes without writing any javascript with the `data-reflex` attribute.
+  
+  ````