dev-notes/AGENTS.md

Repository Guidelines

Project Structure & Module Organization

• Root Markdown notes live alongside README.md; add new docs near related topics to keep discovery simple.
• Use clear filenames with kebab-case (api-integration-notes.md) and group related references with optional directories if a topic grows.
• .vscode/ holds workspace preferences; avoid committing personal or machine-specific settings.

Build, Test, and Development Commands

• No build pipeline is required; files are plain Markdown.
• If you have markdownlint installed locally, run npx markdownlint "**/*.md" to catch common formatting issues.
• Use a Markdown preview in your editor to verify headings, lists, and code blocks render as expected.

Coding Style & Naming Conventions

• Write in concise, direct prose; prefer short sections with descriptive headings.
• Use fenced code blocks with language hints ( ```js, ```bash) and avoid trailing whitespace; wrap lines around 100 characters for readability.
• Favor ordered lists for sequences and unordered lists for checklists; keep tables minimal.
• Filenames: lowercase kebab-case; avoid spaces and punctuation beyond dashes.

Testing Guidelines

• Proofread for accuracy and broken references before publishing.
• Run npx markdownlint "**/*.md" when available; resolve lint warnings instead of suppressing them.
• For code snippets, include the minimal runnable example; note prerequisites if a command depends on a tool or version.

Commit & Pull Request Guidelines

• Commit messages: imperative mood, short summary (docs: add api auth notes), followed by optional detail in the body.
• Keep commits scoped to a single topic (one note or one refactor) to simplify review.
• Pull requests should describe the intent, list key changes, and call out any TODOs or open questions.
• Link related issues or tasks when applicable and add screenshots only if rendering changes are involved.

Security & Configuration Tips

• Do not store secrets, tokens, or private endpoints in notes; use placeholders (<token>) and reference secure vault locations instead.
• If sharing configuration snippets, redact hostnames and credentials and prefer environment-variable examples.