From ea5c01a545fbd13115b204895336940b54a11334 Mon Sep 17 00:00:00 2001
From: Brittany Ellich <brittanyellich@github.com>
Date: Thu, 16 Apr 2026 22:10:35 -0700
Subject: [PATCH] Update readme

---
 README.md | 110 ++++++++++++++++++++++++++++++++++++++++--------------
 1 file changed, 83 insertions(+), 27 deletions(-)

diff --git a/README.md b/README.md
index 87b813a..3adb319 100644
--- a/README.md
+++ b/README.md
@@ -1,43 +1,99 @@
-# Astro Starter Kit: Minimal
+# atmosphere.community
+
+The community hub for the [AT Protocol](https://atproto.com/) ecosystem. Aggregates blog posts from [Offprint](https://blog.atmosphere.community), upcoming events from [Smoke Signal](https://smokesignal.events) and community accounts, and links to regional AT Protocol communities and apps.
+
+Built with [Astro](https://astro.build/) and deployed to GitHub Pages.
+
+## Getting started
 
 ```sh
-npm create astro@latest -- --template minimal
+npm install
+npm run dev
 ```
 
-> 🧑‍🚀 **Seasoned astronaut?** Delete this file. Have fun!
+The dev server starts at `localhost:4321`. The site fetches live data from ATProto at build time (blog posts, events), so you'll need internet access for a full build.
+
+### Commands
 
-## 🚀 Project Structure
+| Command           | Action                                       |
+| :---------------- | :------------------------------------------- |
+| `npm install`     | Install dependencies                         |
+| `npm run dev`     | Start local dev server at `localhost:4321`    |
+| `npm run build`   | Build production site to `./dist/`           |
+| `npm run preview` | Preview the build locally before deploying   |
 
-Inside of your Astro project, you'll see the following folders and files:
+### Deployment
 
-```text
-/
-├── public/
-├── src/
-│   └── pages/
-│       └── index.astro
-└── package.json
+The site deploys to GitHub Pages automatically via the workflow in `.github/workflows/deploy.yml`. It runs on:
+
+- Push to `main`
+- Every 6 hours (cron) to pick up new blog posts and events
+- Manual trigger via `workflow_dispatch`
+
+## Project structure
+
+```
+src/
+├── components/        # Astro components (Header, Footer, Hero, cards)
+├── data/
+│   ├── apps.yml       # App directory listings
+│   └── communities.yml # Community group listings
+├── layouts/
+│   └── Base.astro     # Base HTML layout
+├── lib/
+│   ├── atproto.ts     # ATProto helpers (profile resolution)
+│   ├── blog.ts        # Blog post fetcher (standard.site documents)
+│   └── events.ts      # Event fetcher (community.lexicon.calendar.event)
+├── pages/
+│   ├── index.astro    # Homepage
+│   ├── about.astro    # About page
+│   ├── apps.astro     # App directory
+│   ├── communities.astro # Community listings
+│   └── events.astro   # Events listing
+└── styles/
+    └── global.css     # Design system (tokens, reset, utilities)
 ```
 
-Astro looks for `.astro` or `.md` files in the `src/pages/` directory. Each page is exposed as a route based on its file name.
+## Adding content
 
-There's nothing special about `src/components/`, but that's where we like to put any Astro/React/Vue/Svelte/Preact components.
+### Add a new app
 
-Any static assets, like images, can be placed in the `public/` directory.
+Edit `src/data/apps.yml` and add an entry:
+
+```yaml
+- name: My App
+  description: A short 1-2 sentence description of what the app does.
+  url: https://myapp.example
+  bluesky: https://bsky.app/profile/myapp.example  # optional
+  category: Social  # Social, Events, Publishing, Developer Tools, Tools, Identity, Community
+  logo: /images/apps/myapp.png  # optional — drop image in public/images/apps/
+```
+
+If you include a logo, place the image file (PNG, SVG, or WebP, ideally 180×180) in `public/images/apps/`. If omitted, a colored-initial icon is generated automatically.
+
+### Add a new community
+
+Edit `src/data/communities.yml` and add an entry:
+
+```yaml
+- name: ATProto My City
+  handle: mycity.atproto.camp
+  location: My City, ST
+  description: My City ATProtocol user group
+  bluesky: https://bsky.app/profile/mycity.atproto.camp
+```
 
-## 🧞 Commands
+Community accounts are also used to fetch events — any `community.lexicon.calendar.event` records on the account's PDS will automatically appear on the Events page and homepage.
 
-All commands are run from the root of the project, from a terminal:
+## Data sources
 
-| Command                   | Action                                           |
-| :------------------------ | :----------------------------------------------- |
-| `npm install`             | Installs dependencies                            |
-| `npm run dev`             | Starts local dev server at `localhost:4321`      |
-| `npm run build`           | Build your production site to `./dist/`          |
-| `npm run preview`         | Preview your build locally, before deploying     |
-| `npm run astro ...`       | Run CLI commands like `astro add`, `astro check` |
-| `npm run astro -- --help` | Get help using the Astro CLI                     |
+| Data | Source | Fetched at |
+|------|--------|-----------|
+| Blog posts | [Offprint](https://blog.atmosphere.community) via `site.standard.document` XRPC | Build time |
+| Events | [Smoke Signal](https://smokesignal.events) / community accounts via `community.lexicon.calendar.event` XRPC | Build time |
+| Communities | Static YAML (`src/data/communities.yml`) | Build time |
+| Apps | Static YAML (`src/data/apps.yml`) | Build time |
 
-## 👀 Want to learn more?
+## License
 
-Feel free to check [our documentation](https://docs.astro.build) or jump into our [Discord server](https://astro.build/chat).
+MIT
-- 
2.51.2