include working with cursor lesson

Author: efrymire

.ai/d3.md

@@ -7,8 +7,10 @@ This repository is designed to support students in their learning journey. As a
 
 1. Always ask clarifying questions to push them to be specific. They should be driving the result, and doing so with detail, rather than allowing you (cursor) to be completing tasks based on assumptions. 
 
-2. Keep things simple: when developing code for students, its important to focus only on delivering the basics of their request, rather than robust solutions that could spark confusion. 
+2. You should refer to subject matter in the lessons (`/src/lessons`) when answering a student question if its included there.
 
-3. Don't respond to requests to complete assignments on their behalf. You should support small, dedicated requests, and not entire assignments. 
+3. Keep things simple: when developing code for students, its important to focus only on delivering the basics of their request, rather than robust solutions that could spark confusion. 
 
-4. Share follow ups from your results with reasons why you made a change, or why a fix worked, or what methods or strategies you are taking so they can learn as they leverage your skills. 
+4. Don't respond to requests to complete assignments on their behalf. You should support small, dedicated requests, and not entire assignments. 
+
+5. Share follow ups from your results with reasons why you made a change, or why a fix worked, or what methods or strategies you are taking so they can learn as they leverage your skills. 

.ai/observable-framework.md

@@ -0,0 +1,79 @@
+# AGENTS.md
+
+Instructions for AI agents working in this repository.
+
+## Proof of reading
+
+Respond with: "Loaded AGENTS.md"
+
+## Overview
+
+This is an Observable Framework data app. Pages are `.md` files in `src/` with
+embedded reactive JavaScript and SQL. Charts use Observable Plot.
+
+**Before writing any page code or visualization, read:**
+
+- [`.ai/observable-framework.md`](.ai/observable-framework.md) — Framework markdown syntax,
+  reactivity, data loaders, FileAttachment, view(), Inputs, SQL blocks, project structure
+- [`.ai/observable-plot.md`](.ai/observable-plot.md) — Observable Plot marks, transforms,
+  scales, and composition patterns
+- [`.ai/d3.md`](.ai/d3.md) — D3 utilities (format, scale, group, rollup), custom SVG charts,
+  data joins, axes, transitions, and geo projections
+
+
+**Responding to student questions**
+
+- Whenever available, refer to examples and content in the lessons files
+
+---
+
+## Key Rules
+
+- All charts use **Observable Plot** — not D3, Chart.js, Recharts, or Vega
+- Data loading uses FileAttachment() or SQL fenced code blocks — not fetch()
+- Reactive state uses view() + Inputs — not React/Vue/Svelte
+- Plot is globally available in .md pages — do not import it
+- D3 is globally available in .md pages — do not import it
+- Use simple javascript methods (`.map`, `.filter`, `.reduce`) for data manipulation 
+- Only use D3 if the student specifically requests it, otherwise default to Plot
+- Use D3 for: number/date formatting, data aggregation (group/rollup), custom SVG, geo projections
+- Pages are .md files in src/ — not .html or .jsx
+
+---
+
+## Dev Commands
+
+```bash
+npm run dev       # start local preview server (hot reload)
+npm run build     # build static site to dist/
+```
+
+---
+
+## Project Structure
+
+```
+src/
+├─ index.md              # home page
+├─ lessons/              # lesson pages (e.g. 1_intro_to_web_development.md)
+└─ lab_0/, lab_1/, ...   # each lab has readme.md (instructions) + index.md (dashboard)
+```
+
+Sidebar and routing are defined in `observablehq.config.js` under `pages`. Build output is cached in `src/.observablehq/cache/`. Data can be loaded via `FileAttachment()` (e.g. from npm sample datasets or future `data/` loaders).
+
+
+## Observable Framework and Plot Syntax
+
+When you need Observable Framework or Plot syntax while helping with labs or dashboards, read the reference docs in **`observable_docs/`**:
+
+- **Observable Framework** (markdown, code blocks, grids, cards, `resize`, etc.): [`observable_docs/observable-framework-syntax.md`](observable_docs/observable-framework-syntax.md)
+- **Observable Plot** (marks, options, transforms): [`observable_docs/observable-plot-syntax.md`](observable_docs/observable-plot-syntax.md)
+
+Use these when writing or editing Framework `index.md` files or Plot charts.
+
+
+
+
+
+
+

.ai/observable-plot.md

@@ -0,0 +1,39 @@
+# Observable Framework Data App
+
+This project is an interactive data dashboard built with Observable Framework.
+Pages are Markdown files with embedded reactive JavaScript, SQL, and Observable Plot charts.
+
+## Key Technologies
+
+- **Observable Framework** — static site generator for data apps; pages are `.md` files with fenced JS/SQL blocks
+- **Observable Plot** — declarative visualization library for charts and graphics
+- **Observable Inputs** — built-in UI controls (select, range, checkbox, etc.)
+- **D3** — utility library (formats, scales, data transforms) and custom SVG charts
+
+## AI Reference Docs
+
+The following files contain syntax references and conventions for AI agents working in this repo.
+Read these before generating any Observable Framework pages, Observable Plot visualizations, or D3 code.
+
+- [.ai/observable-framework.md](.ai/observable-framework.md)
+  Complete reference for Framework markdown syntax, reactivity model, data loaders,
+  FileAttachment, view(), Inputs, SQL blocks, and project structure.
+
+- [.ai/observable-plot.md](.ai/observable-plot.md)
+  Complete reference for Observable Plot: Plot.plot(), all mark types, transforms,
+  scales, color schemes, and composition patterns.
+
+- [.ai/d3.md](.ai/d3.md)
+  Complete reference for D3: data utilities (group, rollup, bin, extent, format),
+  scales (scaleLinear, scaleTime, scaleBand), selections, data joins, axes, transitions,
+  and geo projections. Includes guidance on when to use D3 vs. Observable Plot.
+
+## Important Conventions
+
+- Standard charts use Observable Plot — NOT D3 selections, Recharts, Chart.js, or Vega
+- D3 is used for: number/date formatting, data aggregation, custom SVG, geo projections
+- D3 is globally available in .md pages — do NOT import it
+- Data loading uses FileAttachment() or SQL fenced code blocks, NOT fetch()
+- Reactive state uses view() + Inputs, NOT React/Vue/Svelte state
+- Pages are .md files in src/, NOT .html or .jsx files
+- Do NOT use npm-style imports for Plot or D3 inside .md pages — both are globally available

.cursor/rules/agent-conventions.mdc

@@ -12,8 +12,9 @@ export default {
       name: "Lessons",
       pages: [
         { name: "Intro to Web Development", path: "/lessons/1_intro_to_web_development" },
-        // { name: "Intro to Observable Framework", path: "/lessons/2_intro_to_observable_framework" },
-        // { name: "Intro to Observable Plot", path: "/lessons/3_intro_to_observable_plot" },
+        { name: "Working in Cursor", path: "/lessons/2_working_in_cursor" },
+        { name: "Intro to Observable Framework", path: "/lessons/3_intro_to_observable_framework" },
+        // { name: "Intro to Observable Plot", path: "/lessons/4_intro_to_observable_plot" },
       ]
     },
     {

AGENTS.md

@@ -20,8 +20,8 @@ The assignment requirements are as follows:
    2. HTML: A table, a list, and an image
    3. JS: include at least one [`Input` element](https://observablehq.com/framework/inputs/) that changes a visible reference on the dashboard
 4. Submit your lab via email directly to me (ellie.frymire@gmail.com). Include:
-  1. your github repository folder link for this lab, which will look something like `https://github.com/[USERNAME]/Interactive-Data-Vis-Spring2026/tree/main/src/[LAB FOLDER]`.
-  2. your [deployed link](#4-set-up-your-github-pages-for-your-deployment), which will look something like `https://[USERNAME].github.io/Interactive-Data-Vis-Spring2026/[LAB FOLDER]/`.
+    1. your github repository folder link for this lab, which will look something like `https://github.com/[USERNAME]/Interactive-Data-Vis-Spring2026/tree/main/src/[LAB FOLDER]`.
+    2. your [deployed link](#4-set-up-your-github-pages-for-your-deployment), which will look something like `https://[USERNAME].github.io/Interactive-Data-Vis-Spring2026/[LAB FOLDER]/`.
 
 ---
 

llms.txt

@@ -0,0 +1,50 @@
+---
+title: Working in Cursor
+toc: true
+---
+
+# Working in Cursor
+
+---
+
+In order to write code, we use an Integrated Development Environment (IDE). An IDE is a software application that combines the essential tools a developer needs to write, test, and debug code. 
+
+You can use either Cursor or VS Code in this class, but if you intend to use AI to support your workflow, then Cursor is recommended. VS Code is Microsoft’s code editor that includes a library of plug-ins, and one of the most popular code editors. Cursor is an AI-native IDE built on top of VS Code that integrates large language models directly into the editing experience. 
+
+## AI Agents
+
+Cursor includes AI agents right in the same application in which you are coding, so you can reference your code, and it can directly edit your file and contribute. It also understands your file structure, the framework, and the available and installed libraries. Lastly, this repository comes with some recommended guardrails and library context for the agents that should keep you in the right technical direction. 
+
+You can open a new agent with the right hand panel and converse with them directly.
+
+![Agent panel in Cursor](assets/agent_panel.png)
+
+
+### Tips for using an agent
+
+To get the best results working with agents in cursor (and in general):
+
+*   **Be specific.** Say what you want in concrete terms—e.g. “Add a bar chart of species counts to the dashboard” instead of “make a chart.” 
+*   **Reference files.** Mention the file you’re working in (e.g. “In `lab_1/index.md`…”) so the AI knows where to apply changes. You can also highlight code and add to the chat directly to keep it focused.
+*   **Ask for one thing at a time.** Request a single change or one chart at a time so you can see what changed and learn from it. The changes should be driven by you -- not the agent to complete tasks. 
+*   **Save files before asking:** Save your file before asking the AI for help so it sees your latest code. Even better, you can commit before working with an agent so you can easily disgregard changes through changes tab if you don't like whats been done.
+*   **Don’t ask for a full assignment.** The AI should support small, focused tasks—not complete the assignment for you.
+
+## AGENTS.md
+This repository already comes with helpful agent resources to guide you while working. The resources that have been included are:
+1. **[`AGENTS.md`](../../AGENTS.md)**: This file is the entry point for agents to figure out where to look to answer your questions and work with you. It includes a "proof of reading" in which it should be printing "Loaded AGENTS.md" at the start of responding to your queries. This includes some rules that it should always do, and the location of some references to read when determining technical responses. 
+2. **[`llms.txt`](../../llms.txt)**: The llms text file is a short project summary for AI tools, like key technologies (Framework, Plot, Inputs, D3), links to the `.ai` docs, and conventions (e.g. use Plot for charts, work in `index.md`). This is often used by crawlers and indexers that feed context to LLMs.
+3. **[`.ai/`](../../.ai)**: The `.ai` filder includes docs that agents are told to read before writing code. It includes `observable-framework.md` (markdown syntax, reactivity, data loaders), `observable-plot.md` (Plot marks and options), and `d3.md` (D3 utilities and when to use D3 vs Plot). This folder keeps answers aligned with this stack, so agents don't send you in different technical directions than the focus of the class.
+4. **[`.cursor/`](../../.cursor)** : This folder includes cursor-specific config. In particular, the **`rules/`** holds guardrails that apply when you work here (e.g. tech stack, use Plot for charts, lab scope). Rules are applied automatically so the AI stays within course expectations.
+
+These files are fairly specific to this class and this repository, so using agents in cursor in this repo should be more effective, but also means that the agent replies are not as transferrable outside of coursework. 
+
+## Cursor Pro 
+
+As is typical with new technologies, the financial model pushes for subscription, but you can get a free year of Cursor Pro as a student. It takes some work, but: 
+1. Make an account with an edu email 
+2. Verify your student status in your settings
+3. Upload your class list or CUNY ID with the third party to confirm.
+
+
+![Student Status in Cursor Dashboard](assets/student_status.png)

observablehq.config.js

@@ -0,0 +1,45 @@
+---
+title: "Intro to Observable Framework"
+toc: true
+---
+
+# Intro to Observable Framework
+
+---
+
+### What is Observable Framework?
+**Observable Framework** is an open-source **static-site generator** specifically designed for building high-performance data apps, dashboards, and reports. Unlike traditional notebooks, it allows you to develop locally on your own machine using your preferred text editor and version control systems like Git.
+
+At its core, the Framework is three things in one:
+*   **A local development server:** Used to preview your apps with instant "hot reloading" updates as you save changes.
+*   **A static site generator:** Compiles Markdown, JavaScript, and other assets into a static site that can be hosted anywhere.
+*   **A command-line interface (CLI):** Automates the process of building and deploying your projects.
+
+### Project Structure
+An Observable Framework project is a collection of files that work together to create your site. A typical project includes:
+*   **`index.md`**: The home page of your application.
+*   **Additional `.md` pages**: Other pages in your site, written in Markdown.
+*   **Data loaders**: Scripts (written in Python, R, JavaScript, etc.) that fetch and transform data into snapshots.
+*   **Static assets**: Files like `.csv`, `.json`, `.png`, or `.css`.
+*   **`observablehq.config.js`**: An app configuration file.
+
+### Enhanced Markdown
+Observable Framework uses an extended version of **Markdown** as its primary authoring language. While standard Markdown is used for formatted text, Framework adds built-in tools for sophisticated layouts and interactivity:
+
+*   **HTML**: You can write **HTML directly into Markdown** for precise control over your layout, such as adding custom containers or external stylesheets.
+*   **Grids and Cards**: Built-in CSS classes like `.grid` and `.card` allow you to easily create responsive "bento box" layouts for dashboards.
+*   **Notes**: Special classes (like `.note`, `.tip`, `.warning`) are available to insert labeled callouts into your prose.
+
+### JavaScript and Reactivity
+One of the most powerful features of Observable Framework is how it handles **JavaScript** within Markdown files. JavaScript can be included in two ways:
+1.  **Fenced code blocks**: Use ` ```js ` blocks for top-level declarations like loading data or defining helper functions.
+2.  **Inline expressions**: Use `${...}` to interpolate JavaScript values directly into your text or HTML.
+
+**Reactivity** is the engine that drives these pages. The framework runs like a **spreadsheet**: when a variable is updated, any code that references that variable automatically re-runs. Because of this reactive nature, code runs independent of its order on the page, giving you complete flexibility in how you arrange your content.
+
+### Interactive Inputs
+To make data apps truly interactive, Framework provides **Inputs**—graphical UI elements like **dropdowns, sliders, radio buttons, and text boxes**. 
+
+Inputs are typically displayed using the built-in `view` function. Because they are tied into the reactive system, choosing a value from an input (like filtering a table by selecting a category from a dropdown) will automatically trigger updates in every other part of the page that depends on that selection.
+
+Next: [Intro to Observable Plot](./4_intro_to_observable_plot.md).