docs: prepare Build Week submission

README.md

@@ -10,6 +10,26 @@ It is not an emergency or medical service, does not prescribe or sell medicine,
 and does not process payments. A helper may publish an optional external
 thank-you link; money goes directly between users outside the platform.
 
+## OpenAI Build Week 2026
+
+Who Need Help was created during the OpenAI Build Week submission period. The
+entrant supplied the real-world problem, product priorities, safety decisions,
+and deployment constraints. Codex running GPT-5.6 (`gpt-5.6-sol`) was used to
+turn those decisions into the Phoenix application, tests, deployment tooling,
+documentation, and browser verification. Important product choices—voluntary
+help, medicine-first scope, consent-based tracking, two-party handover, and no
+platform payments—remain human decisions rather than model-generated policy.
+
+The deployed application does not call the OpenAI API and contains no OpenAI
+API key. Optional category-review assistance runs only through the operator's
+local Codex CLI authenticated with their ChatGPT subscription.
+
+- Codex session ID for `/feedback`:
+  `019f725d-87b5-79e1-8a9f-66e6eaffb35a`
+- Public test build: <https://test.whoneedhelp.com>
+- [Devpost submission draft and demo script](docs/devpost-submission.md)
+- [Implementation and verification evidence](docs/verification.md)
+
 ## What is implemented
 
 - Phoenix 1.8 LiveView application with passwordless email magic links,
@@ -304,12 +324,12 @@ an explanation. A partial pair is rejected at startup and by the production
 environment validator.
 
 The flow requests `openid email profile`, verifies the provider email claim,
-uses state, nonce, and PKCE, and discards provider tokens. Google registration
+uses state, nonce, and PKCE, and discards provider tokens. A new Google identity
-creates a confirmed local account only after the user accepts the 18+ safety
+continues to a safe registration-completion page and creates a confirmed local
-terms. Google login works only for an identity already linked to that local
+account only after the user accepts the 18+ safety terms. A returning linked
-account. An existing local account is never merged merely because Google
+identity signs in directly. An existing local account is never merged merely
-returns the same email; sign in by email or password and connect Google from
+because Google returns the same email; sign in by email or password and connect
-the sudo-protected account settings page instead. Leave
+Google from the sudo-protected account settings page instead. Leave
 `GOOGLE_OAUTH_BASE_URL` and the Google HTTP timeout variables empty outside the
 isolated protocol drill.
 

docs/devpost-submission.md

@@ -0,0 +1,136 @@
+# Who Need Help — Devpost submission draft
+
+This document is a ready-to-copy draft for the OpenAI Build Week submission.
+It separates verified project facts from actions that still require the
+entrant's Devpost and YouTube accounts.
+
+## Registration and final submission checklist
+
+1. Personally confirm eligibility under the official rules: age of majority,
+   supported location, and none of the listed exclusions or conflicts.
+2. Create a free Devpost account or sign in, confirm its email if requested,
+   open the event page, and select **Join Hackathon**.
+3. Start the project submission and use the fields drafted below.
+4. Record and upload a public YouTube demonstration shorter than three minutes,
+   with clear audio and no unlicensed music or third-party marks.
+5. Keep the repository private and grant access to
+   `testing@devpost.com` and `build-week-event@openai.com`, or make it public
+   only after the owner deliberately selects and adds a license.
+6. Add the public YouTube URL, test-build URL, repository URL, and Codex
+   `/feedback` session ID; preview every field and submit before the deadline.
+
+Official references:
+
+- <https://openai.devpost.com/rules>
+- <https://openai.devpost.com/details/faqs>
+- <https://openai.devpost.com/>
+
+## Submission fields
+
+- **Project name:** Who Need Help
+- **Track:** Apps for Your Life
+- **Tagline:** Fast, local, voluntary help when every minute matters.
+- **Demo build:** <https://test.whoneedhelp.com>
+- **Repository:** <https://git.imalto.site/simpletest/who_need_help>
+- **Codex `/feedback` session ID:**
+  `019f725d-87b5-79e1-8a9f-66e6eaffb35a`
+- **YouTube demo:** not uploaded yet
+- **Built with:** Elixir, Phoenix 1.8, LiveView, PostgreSQL/PostGIS, Oban,
+  MapLibre, Docker Compose, Helm, Kotlin/Android, Codex, and GPT-5.6.
+
+## Description
+
+Who Need Help connects a person with an urgent, non-emergency need to a nearby
+volunteer. Its first use case is medicine pickup: when a pharmacy or ordinary
+delivery service cannot deliver in time, a volunteer can coordinate the pickup
+and handover. The same data-driven flow already supports fuel, wheel, bicycle,
+motorcycle, vehicle-breakdown, and secured-road-incident help without turning
+the product into a marketplace or emergency service.
+
+The requester creates a categorized request and initially exposes only an
+approximate area. A volunteer accepts it, then both people coordinate in a
+private real-time chat. The requester can opt into live location sharing for
+the active match. A one-time handover code and confirmation by both parties
+complete the request. Double-blind reviews, unique-counterpart reputation,
+blocking, scoped reports, and optional movement evidence reduce trivial rating
+manipulation without pretending to provide guaranteed identity verification.
+
+The platform is free and does not process payments. A helper may publish an
+optional external thank-you link after completion, but any transfer happens
+directly between users. It is not a medical, pharmacy, emergency, transport,
+or payment service.
+
+The architecture is intentionally extensible. Categories and their validated
+fields live in PostgreSQL, and users can propose and vote on missing categories
+for human moderation. Social activities—coffee, cinema, walks, and hikes—use a
+separate lifecycle and never affect urgent-help reputation. The same immutable
+release can run compactly on one server with Docker Compose or scale into
+separate web and worker replicas and a later Kubernetes deployment.
+
+## How Codex and GPT-5.6 were used
+
+The entrant brought the problem, priorities, policy decisions, domain access,
+and deployment constraints. Codex running GPT-5.6 (`gpt-5.6-sol`) helped turn
+that direction into working software: Phoenix contexts and LiveViews,
+PostGIS-backed location handling, real-time messaging, safety and privacy
+controls, an Android client, Docker/Helm operations, automated tests, and the
+verification documentation.
+
+Codex was also used as an engineering reviewer. It inspected the code and
+queries, ran the test/security/performance gates, drove two independent headed
+browser sessions through the end-to-end workflow, checked persisted database
+effects, and repaired defects found during verification. One concrete example:
+blocking correctly rejected chat messages on the server, but the blocked
+request page still rendered a message form. The browser audit exposed that UX
+gap; the LiveView now hides the form, shows an explicit blocked state, and has
+a regression test.
+
+The application itself does not call the OpenAI API and does not require an
+OpenAI API key. Its optional category-review tool runs only through the
+operator's local ChatGPT-authenticated Codex CLI and receives a PII-free export.
+
+## Judge access
+
+The public test build does not require payment or a private network. Two
+dedicated test accounts exercise requester and helper roles; their credentials
+are stored outside Git in `output/devpost-testing-instructions.txt` and should
+be copied into Devpost's private testing-instructions field. Test email is
+captured by the isolated test Mailpit and is not a production delivery claim.
+
+## Demonstration script (target: 2 minutes 45 seconds)
+
+- **0:00–0:18 — Problem.** Explain the late medicine-pickup scenario and that
+  this is voluntary non-emergency coordination, not a pharmacy or courier.
+- **0:18–0:42 — Create.** Register or sign in as the requester, create a
+  medicine request, show category-specific fields and approximate-area privacy.
+- **0:42–1:05 — Match.** In the helper browser, discover and accept the request;
+  show both browsers updating and exchange one private chat message.
+- **1:05–1:28 — Track.** Start consent-based location sharing, move the helper
+  marker, and point out that raw current positions are removed when sharing
+  stops.
+- **1:28–1:52 — Verify.** Enter the handover code, confirm from both accounts,
+  submit double-blind reviews, and show the helper leaderboard.
+- **1:52–2:15 — Extend and protect.** Briefly show category proposals, Activity
+  mode, privacy settings, block/report controls, and support/removal forms.
+- **2:15–2:38 — Engineering.** Show one Compose deployment, separate web/worker
+  roles, PostgreSQL/PostGIS, the passing test count, and the verification doc.
+- **2:38–2:45 — Codex.** State that Codex with GPT-5.6 implemented and audited
+  the project with the entrant, then show the public test URL.
+
+## Verified evidence and remaining external actions
+
+The current test release passed 286 Phoenix tests. A headed two-account browser
+run completed registration, request creation, matching, chat, two-point live
+tracking, tracking cleanup, handover, both-party completion, double-blind
+reviews, leaderboard, privacy persistence, category proposal/vote, Activity
+approval/chat/completion, message-scoped reporting, and block/unblock behavior.
+The regression found during that run was fixed, retested in the browser, and
+committed.
+
+The following are intentionally not claimed complete:
+
+- the public YouTube demonstration has not been recorded or uploaded;
+- Devpost registration, eligibility confirmation, repository access sharing,
+  and the final submission have not been performed;
+- production promotion is separate from the tested deployment and requires
+  explicit owner authorization.

docs/verification.md

@@ -28,6 +28,25 @@ results from product limits and unknown production properties.
 
 ## Reproducible checks
 
+- On 2026-07-21, commit `437650d5e2c376b7e4254265c022fff67bbafb6f`
+  was deployed only to `https://test.whoneedhelp.com`. Two independent headed
+  Chrome contexts registered dedicated requester and helper accounts and
+  completed the medicine-request lifecycle: validated creation, discovery,
+  acceptance, realtime chat, start, two consented location samples, realtime
+  marker movement, tracking stop and raw-position cleanup, handover code,
+  both-party completion, double-blind reviews, and leaderboard update. The same
+  run verified privacy-setting persistence, category proposal/vote, Activity
+  creation/join approval/private chat/exact-location disclosure/completion,
+  message-scoped reporting, and block/unblock behavior. Read-only database
+  checks confirmed two tracking samples, 175.73 metres of aggregate movement,
+  no active tracking session or stored current position after stop, and review
+  reveal only after both reviews existed. A blocked conversation still rendered
+  its form even though the server rejected the message; that defect was fixed,
+  covered by a regression test, redeployed only to test, and browser-rechecked.
+  The Dockerized Phoenix suite passed 286 tests, format checking passed, and
+  both clean password logins were repeated in fresh headed browser contexts
+  with zero console errors or warnings. Production remained on commit
+  `4f2a9aaacc8eca606f3287df5c8663be49f9595b` throughout this verification.
 - On 2026-07-21, commit `811ddf4c5c3847fbb0c2861e6e72fcd6a9bd91fe`
   was deployed only to `https://test.whoneedhelp.com`. Headed Chrome attached to
   the user's existing dev-port profile completed real Google authorization,