vibe-wrote initial AGENTS.md file for better writing with LLMs

AGENTS.md

@@ -0,0 +1,157 @@
+# Scientific Blog Writing Guidelines
+
+Guidelines for writing casual, accessible scientific content in interactive blog posts.
+
+## Style References
+
+Use these blog posts as inspiration for writing style:
+
+- [The Smol Training Playbook](https://huggingface.co/spaces/HuggingFaceTB/smol-training-playbook)
+- [Transformers Tenets](https://huggingface.co/spaces/transformers-community/Transformers-tenets)
+- [FineWeb: decanting the web for the finest text data at scale](https://huggingface.co/spaces/HuggingFaceFW/blogpost-fineweb-v1)
+- [FineVision: Open Data is All You Need](https://huggingface.co/spaces/HuggingFaceM4/FineVision)
+- [The Ultra-Scale Playbook](https://huggingface.co/spaces/nanotron/ultrascale-playbook)
+
+## Voice and Tone
+
+- **Conversational but precise**: Write like explaining to a curious colleague over coffee
+- **Direct address**: Use "you" and "we" freely
+- **Active voice**: Prefer "the model learns" over "learning is performed by the model"
+- **Short sentences**: Break complex ideas into digestible chunks
+- **No hedging**: Say "X improves Y" not "X tends to potentially improve Y"
+
+## Punctuation
+
+- **No em-dashes (—)**: Use parentheses, commas, or separate sentences instead
+- **En-dashes (–)** for ranges only: "2020–2024", "pages 10–15"
+- **Minimal semicolons**: Prefer two sentences over one with a semicolon
+
+## Formatting
+
+- **Bold for key terms** on first introduction
+- **Inline code** for technical identifiers: model names, hyperparameters, file paths
+- Lists for features, steps, or comparisons
+- Keep paragraphs short (3-5 sentences max)
+
+## Structure
+
+- Start sections with the conclusion or key insight
+- Use progressive disclosure: overview first, details on demand
+- Every claim should have a visible artifact (chart, code, demo) nearby
+- Sidenotes for tangential but useful context
+
+## Technical Writing
+
+- Define jargon on first use
+- Concrete examples over abstract explanations
+- Show, don't tell: prefer an interactive demo over a paragraph of description
+- Link to sources, don't just cite them
+
+## Interactivity
+
+- Treat figures as first-class content, not decoration
+- Interactive elements should reveal insight, not just look fancy
+- Ensure all visualizations work in dark mode
+- Mobile-friendly is mandatory
+
+## Content Structure
+
+- **One file, one article**: Main content lives in `app/src/content/article.mdx`
+- **Chapters for length**: Split long articles into `app/src/content/chapters/` and import them
+- **Short sections**: Each section answers one question or supports one idea
+- **TOC-friendly headings**: Use H2–H4 with short, descriptive titles (auto-generates table of contents)
+
+## Math Notation
+
+- **Introduce symbols** the first time they appear
+- **Prefer well-known notation** over custom shorthand
+- **Plain-language interpretation** after every significant formula
+- Inline math: `$x^2$`, block math: `$$...$$`
+- Use `\htmlId{name}{...}` for cross-referenceable equations
+
+## Citations and References
+
+- Citations from `app/src/content/bibliography.bib` using `[@key]` or `@key`
+- Footnotes: `[^id]` with definition `[^id]: explanation`
+- Deep-link anything with `id` prop on `Image`, `HtmlEmbed`, `Reference` components
+- Link format: `[Figure 1](#my-figure-id)`
+
+## Components Quick Reference
+
+| Component | Use for |
+|-----------|---------|
+| `<Sidenote>` | Contextual notes in the margin |
+| `<Note variant="info/success/danger">` | Callouts, tips, warnings |
+| `<Accordion>` | Collapsible details, code examples |
+| `<Image>` | Optimized images with captions, zoom |
+| `<HtmlEmbed>` | D3/Plotly charts, interactive figures |
+| `<Wide>` / `<FullWidth>` | Break out of content column |
+| `<Glossary>` | Hover definitions for terms |
+| `<Quote>` | Attributed quotations |
+| `<Stack>` | Multi-column layouts |
+
+## Chart Selection
+
+Match visualization to analytical goal:
+- **Compare values**: Bar, dot plot
+- **Show distribution**: Histogram, box plot, violin
+- **Part-to-whole**: Pie, stacked bar, treemap
+- **Trends over time**: Line chart
+- **Relationships**: Scatter, bubble
+- **Flow/process**: Sankey, flowchart
+
+Prefer D3 over Plotly for custom, web-native visualizations.
+
+---
+
+## Skills
+
+### Vibe Coding D3 Charts
+
+Create interactive D3 charts as self-contained HTML fragments. Charts must be **responsive**, **accessible**, **interactive**, and **dark mode ready**.
+
+**Workflow:**
+
+1. Read the directives at `app/src/content/embeds/vibe-code-d3-embeds-directives.md`
+2. Optionally use an existing chart from `app/src/content/embeds/` as a starting point
+3. Generate the chart with a prompt like:
+   ```
+   I want you to code a new d3 chart named `yourchart`.
+   I have one CSV file called `yourdata.csv` in the data folder.
+   The csv has the following columns: `x`, `y`, `z`.
+   ```
+4. Iterate with small adjustments until satisfied
+
+**Embedding:**
+
+Use the `<HtmlEmbed>` component in MDX:
+
+```jsx
+<HtmlEmbed
+  id="fig1"
+  src="your-chart.html"
+  title="Chart Title"
+  desc="Figure 1: Description of the chart."
+/>
+```
+
+**Reference examples:** `app/src/content/chapters/demo/vibe-coding-charts.mdx`
+
+---
+
+## End-of-Interaction Checklist
+
+After completing any content edit, perform this reference audit:
+
+1. **Scan for uncited claims**: Look for statements about methods, benchmarks, or prior work that lack citations
+2. **Search for BibTeX entries**: For each missing reference, search online (Google Scholar, Semantic Scholar, arXiv) for the correct BibTeX entry
+3. **Add to bibliography**: Place new entries in `app/src/content/bibliography.bib` with a descriptive key (e.g., `@article{vaswani2017attention, ...}`)
+4. **Insert citations**: Add `[@key]` inline where the reference is needed
+5. **Ask if unsure**: If multiple papers match or authorship is ambiguous, ask the user which reference is correct before adding
+
+**What needs citations:**
+- Model names (BERT, GPT, LLaMA)
+- Datasets (ImageNet, C4, The Pile)
+- Methods and techniques (attention, LoRA, RLHF)
+- Benchmark results or comparisons
+- Claims about prior work ("X showed that...")