Repository Instructions #

This repository is a monorepo containing imported projects and small, independently runnable tools.

Vibe-coded projects #

All new vibe-coded projects must live in their own top-level directory under:

vibe/<project-name>/

Do not place a new vibe-coded project directly at the repository root or inside an unrelated existing project.

Each project under vibe/ must be self-contained and include:

• a useful README.md explaining purpose, setup, common commands, outputs, and limitations
• its own dependency manifest and lockfile when the ecosystem supports one
• its own .gitignore for generated files, local environments, credentials, and secrets
• an .env.example when environment variables are required, containing placeholders only
• automated tests for important behavior and safety boundaries
• commands that can be run from the project's directory without relying on undocumented global state

Safety and repository hygiene #

• Never commit API keys, credentials, .env files, private content, generated reports, or scan results containing source text.
• Preview operations that spend money or mutate remote systems, and require explicit confirmation before executing them.
• Prefer a small canary operation before a paid or large batch operation.
• Keep generated artifacts out of Git unless they are intentional project fixtures.
• Run the project's documented test command before committing.
• Keep changes scoped to the requested project; do not reformat or reorganize unrelated imported projects.

Documentation expectations #

A vibe-coded project's README should let a future maintainer answer, without reading the implementation:

1. What does this project do?
2. How do I install and configure it?
3. How do I run a safe preview or canary?
4. How do I perform the full operation?
5. Where are outputs written, and are they safe to commit?
6. How do I run tests?
7. What external APIs and billing behavior are involved?