# Vibecoded Stuff — Project Guidelines

## Context
This is a personal project folder. Everything built here is for personal use only — no need for production hardening, public documentation, or sharing considerations.

## Before Building Anything
**Ask questions first. Build last.**
- Clarify all specs before writing a single line of code.
- Keep asking until the goal, inputs, outputs, and edge cases are fully clear.
- Only start building once we both agree the spec is complete.

## Project Structure
- Each project gets its own folder: `/home/alex/Documents/vibecoded-stuff/<project-name>/`
- No nested complexity — keep folder structures flat and simple.

## Language Preferences
- **Default to Python** for scripts, tools, automation, data, and CLIs.
- **Use JS/TS** when building frontends or when it's clearly a better fit (e.g., browser-based tools, Node CLIs).
- Avoid introducing other languages unless there's a compelling reason.

## Design Principles
- **Easy to run locally** — no cloud services, no complex infrastructure unless explicitly asked.
- **Easy to use** — the user is non-technical. Favor simple interfaces, clear prompts, and sensible defaults.
- **No unnecessary complexity** — no Docker, no ORMs, no frameworks heavier than the task warrants.
- **Frontends only when requested** — default to CLI or script unless the spec says otherwise.
- **Use established libraries, don't reinvent them** — if something is already industry standard or has a solid, widely-used reference library or open-source project for it, adopt that instead of writing a custom implementation from scratch. This is about supporting the open-source ecosystem, not duplicating or copying its work.

## Style Guide (frontend/HTML/CSS work)
- `/home/alex/Documents/vibecoded-stuff/style.css` is the site style guide. Always use it for any HTML/CSS work in this repo — link it or reuse its tokens/classes instead of inventing new colors, fonts, or spacing.
- Design tokens (colors, fonts, max-width, padding) live in its `:root` block — reuse those vars, don't hardcode values that already have a token.
- Match its existing patterns (section structure, button/card/hero conventions) for new pages instead of introducing a new visual style.

## Data Access
- **Never scrape a website if there's another way to get the data** — check for an official API, RSS/Atom feed, or documented export first, and use that instead.
- Scraping is a last resort, only when no such alternative exists. Prefer it to be low-frequency and respectful (reasonable delays, caching results, honoring robots.txt) rather than repeated/greedy polling.

## Code Style
- No docstrings, no type annotations, no comments unless the logic genuinely needs explanation.
- No extra error handling for impossible scenarios.
- No abstractions for hypothetical future needs.
- Keep dependencies minimal.