# Birdseyeview agent handbook

Birdseyeview is a shared monorepo for small, surprising, browser-native design projects. Each agent gets a namespace and is expected to leave behind a project that another person can open, understand, and deploy without a tour.

## Mission

Make an expressive thing that works. A project may be a game, toy, instrument, utility, visual experiment, or tiny world. Favor a strong point of view, a complete interaction loop, and a memorable first screen over feature count.

## Repository contract

- This repo is intentionally zero-build. Projects use static HTML, CSS, and JavaScript unless a future contribution documents a deliberate exception.
- Every project lives at `/<agent-name>/<project-slug>/index.html`.
- Keep an agent's work inside that agent's namespace. Shared root files may be updated when the gallery or deployment instructions need to know about a new project.
- Use relative asset paths so a project works at a nested Vercel URL, not only at `/`.
- Do not require a server, API key, database, or remote asset for the core experience. If an enhancement is optional, the project must still feel finished offline.
- Prefer browser APIs and graceful fallbacks. Persist small user-created state with `localStorage` only when it improves the loop.
- Keep controls keyboard reachable, label inputs, support narrow screens, and respect `prefers-reduced-motion` where motion is part of the design.

## URL and naming convention

The public shape is:

```text
https://<managed-domain>/<agent-name>/<project-slug>/
```

Use lowercase kebab-case for both path segments. The first segment is the submitting agent's chosen name. The root gallery should link to every project with a short title, one-line premise, and interaction hint.

## What every project should ship

1. A self-contained `index.html` with a visible title and a way back to the gallery.
2. Local styles in `styles.css` (or a clearly named equivalent).
3. Local behavior in `app.js` (or a clearly named equivalent).
4. A clear first action within one viewport.
5. A useful empty state, reset path, and a small-screen layout.
6. No console errors on a fresh load.

## Quality pass before handoff

- Open the project directly from its nested path, not only through the root page.
- Test the primary loop with a mouse and keyboard.
- Test at a phone-sized viewport and a desktop-sized viewport.
- Confirm refresh behavior, reset behavior, and any saved state.
- Check that links do not assume the domain or root path.
- Add the project to the root gallery and keep the project registry text current.
- Describe the premise, controls, and deployment assumption in the project source or its nearby README when the interaction is not self-evident.

## Vercel handoff

Deploy the repository root as a static site. In the Vercel dashboard, use the managed domain supplied by the owner, choose `Other` when a framework preset is required, and leave the build command and output directory empty. Every folder's `index.html` is then available at its matching nested URL. `vercel.json` contains only small static-hosting defaults; do not add rewrites that flatten project paths.

## Collaboration etiquette

Read the root README and this file before touching another agent's namespace. Preserve existing visual identities. If a shared convention must change, update this file and the README in the same change. Keep commits focused when version control is available, and leave a concise note of what was tested.