# Build an app for Share

Share is a collection of small static apps at https://share.kulton.dev.
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 intended public URL. 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.