diff --git a/docs/goals.md b/docs/goals.md
new file mode 100644
index 0000000..00236c1
--- /dev/null
+++ b/docs/goals.md
@@ -0,0 +1,27 @@
+# Goals
+
+Heliosian is a small web application platform for the Helios school community (K-8). It hosts the community's apps — previously run on a no-code platform — as one service, built and maintained in the open by community volunteers.
+
+## What it hosts
+
+The first app is a school directory:
+
+- Names, addresses, phone numbers
+- Individual and family photos
+- Name pronunciation
+
+More apps follow over time, all served by the same binary.
+
+## Principles
+
+- **One static Go binary.** The server is Go, compiled to a static binary, running on Google Cloud Run. New apps are added to the same binary rather than deployed as new services.
+- **Frameworkless client.** Client code is plain JavaScript (TypeScript is an acceptable evolution) with no client-side framework.
+- **Great local development.** A single command runs the server locally. Content changes reload without restarting the server. Non-production sample data makes it possible to develop and test without touching real community data.
+- **Agent-friendly repository.** Most development happens through coding agents driven by a wide community of contributors. The repo is structured, documented, and instrumented (including local screenshot capture) so agents can build, verify, and iterate without human hand-holding.
+- **Open source, minimal configurability.** The code is public and specific to Helios; it does not aim to be a generic configurable product. It contains no secrets, credentials, or private community data.
+
+## Data
+
+- Structured data comes from Google Sheets. The system of record is Veracross, and a direct integration replaces Sheets when an API becomes available.
+- Blobs (photos and other uploads) live in Google Drive.
+- Existing data is imported from the current platforms.
diff --git a/docs/plan.md b/docs/plan.md
new file mode 100644
index 0000000..29934bd
--- /dev/null
+++ b/docs/plan.md
@@ -0,0 +1,50 @@
+# Plan
+
+## Architecture
+
+- Single Go server binary hosting multiple apps under one process, with per-app routing. The directory app is the first; the structure anticipates more.
+- Client is frameworkless JavaScript served by the binary. No build step unless/until TypeScript is adopted, and then a minimal one.
+- Structured data is read from Google Sheets through a data-source abstraction, so a Veracross-backed implementation can replace the Sheets one without touching app code.
+- Photos and other blobs are stored in Google Drive and served through the binary (with caching), never linked directly.
+
+## Hosting and deployment
+
+- Runs on Google Cloud Run.
+- Sign-in is Google authentication restricted to the school's Google Workspace domain. Community-only data is never served to unauthenticated requests.
+- GitHub is the source of truth. Pushes to the main branch trigger an automatic build and deploy to Cloud Run.
+- The Docker build produces a static binary in a minimal base image containing only tzinfo and CA certificates.
+
+## Local development
+
+- One command starts the local server.
+- Templates, static assets, and content reload on change without restarting the server.
+- A local data mode serves generated, non-production sample data so contributors never need real community data to develop or test.
+- A documented screenshot mechanism captures pages from the local dev server, so agents (and humans) can verify visual changes. See `docs/screenshots.md` once it exists.
+
+## Directory app
+
+- Clone the existing app's functionality and layout, working from screenshots of the current app as the reference.
+- Views: browsable/searchable directory of families and individuals; detail pages with contact info, photos, and name pronunciation.
+- Photo handling: individual and family photos uploaded to Drive, resized/cached for serving.
+- Pronunciation: stored per person; representation (text respelling vs. audio) decided during the clone.
+
+## Data
+
+- Sheets layout: one spreadsheet per app, one tab per entity type, first row is the schema. The server reads via the Sheets API with a service account.
+- Import tooling brings existing data from the current platforms into Sheets and Drive.
+- When a Veracross API is available, a second data-source implementation replaces Sheets as the backend for directory data.
+
+## Milestones
+
+1. Repo scaffold: server skeleton, app routing, local dev loop with reload, sample data mode, screenshot tooling, contributor/agent docs.
+2. Directory app read-only clone against sample data.
+3. Google Sheets and Drive integration; real data imported.
+4. Cloud Run service, GitHub auto-deploy pipeline, minimal image build.
+5. Google domain sign-in gating community-only data.
+6. Photo/pronunciation upload flows.
+7. Subsequent apps.
+
+## Open questions
+
+- TypeScript adoption: start with plain JavaScript; revisit if client code grows.
+- Serving domain and Cloud project layout.