# Build an app for Share

Share is a collection of small static apps.
Publishing is Git-based: files in `public/` are deployed by Cloudflare Pages.
There is no upload endpoint, Quick SDK, database, or WebSocket service.

## Workflow

1. Work in the Share repository. Inspect existing files and preserve unrelated work.
2. Choose a short lowercase kebab-case name, such as `coin-flips`. Check that the
   name is unused; do not replace an existing app unless requested.
3. Create `public/coin-flips/index.html`. Keep all app-specific CSS, JavaScript,
   images, and other assets inside `public/coin-flips/`. A single HTML file is fine.
4. Add the app's name, a short description, and a `/coin-flips/` link to the list
   in `public/index.html`. Keep the homepage list alphabetical by displayed name.
5. Preview with `python3 -m http.server 8000 --bind 127.0.0.1 --directory public`.
   Open the app under its directory path, not just a file URL.
6. Test inputs, keyboard access, mobile layout, light/dark appearance, and any
   interactions. Run `node --test tests/*.test.cjs` if Node is available. Add tests
   for new logic when useful; disclose any verification you could not perform.
7. Summarize changes and give the app path (for example, `/coin-flips/`). The owner handles commits
   and pushes unless explicitly asking you to do so. Do not claim the app is live
   until deployment has been confirmed.

## App conventions

- Use ordinary HTML, CSS, and JavaScript with no build step or dependencies by
  default. Do not introduce a framework or site-wide tooling for a small app.
- Reference app assets relatively: `./style.css`, `./app.js`, `./image.svg`.
  Use `/` for a link back to the homepage. Do not hardcode the production host
  in app requests or navigation; local and Pages preview URLs must work too.
- Canonical app URLs end in `/`. Do not assume SPA client-side routing: prefer
  a single page, hash navigation, or actual HTML files for additional routes.
- Match the minimal, slightly brutalist design: readable system fonts, ample
  whitespace, restrained borders, ordinary links and buttons. No unnecessary
  taglines, decorative cards, or elaborate chrome.
- Support system light/dark mode (`color-scheme: light dark` is a useful start).
  Use semantic HTML, visible focus states, associated input labels, and useful
  document titles. Keep long-running work from blocking the page.
- Apps are independent. Do not change other apps or the site's root configuration
  as an incidental part of adding one.
- Reserve root site files and configuration names. Do not add `functions/`,
  `_worker.js`, `_redirects`, `_headers`, or a service worker without approval.

## Safety and scope

All published files and embedded data are publicly accessible. Never include
secrets, tokens, private URLs, personal data, or server-side credentials. A hidden
link is not access control. Render user input as text, not unsanitized HTML.

All apps share one browser origin. Only publish trusted code. localStorage is
browser-local and should use app-prefixed keys; it is not a database shared with
friends. There is no backend or authentication in this version. Ask before adding
external services, analytics, database access, or realtime features.