diff --git a/README.md b/README.md
new file mode 100644
index 0000000..c70c0f1
--- /dev/null
+++ b/README.md
@@ -0,0 +1,115 @@
+# social-updater
+
+Reads a YouTube channel's RSS feed every hour and automatically shares new videos to Facebook and LinkedIn.
+
+## Getting started
+
+```bash
+cp .env.example .env
+# fill in the tokens (see below)
+docker compose up -d
+```
+
+---
+
+## Obtaining API credentials
+
+### `YOUTUBE_CHANNEL_ID`
+
+No registration needed — this is a public RSS feed.
+
+1. Open the channel page on YouTube.
+2. Read it from the URL: `youtube.com/channel/UC...` — the part starting with `UC` is the channel ID.
+3. If the channel has a custom URL (`@handle` format), open the channel's About page, click **Share**, then **Copy channel ID**.
+
+---
+
+### Facebook — `FACEBOOK_ACCESS_TOKEN` and `FACEBOOK_PAGE_ID`
+
+Requirements: a Facebook **App** and a **Page** you have admin access to.
+
+#### 1. Create a Facebook App
+
+1. Go to [Meta for Developers](https://developers.facebook.com/).
+2. Click **My Apps → Create App → Business**.
+3. Enter the app name and create it.
+4. In the app dashboard, add the **Facebook Login** and **Pages API** products.
+
+#### 2. Get a Page Access Token
+
+1. Open the [Graph API Explorer](https://developers.facebook.com/tools/explorer/).
+2. Select your app from the dropdown.
+3. Click **Generate Access Token** and log in with your Facebook account.
+4. Request at least these permissions:
+   - `pages_show_list`
+   - `pages_read_engagement`
+   - `pages_manage_posts`
+5. The generated token is a **User token** — exchange it for a **Page token**:
+   ```
+   GET /{page-id}?fields=access_token
+   ```
+   The `access_token` in the response is your Page Access Token.
+
+#### 3. Long-lived token (recommended)
+
+Short-lived tokens expire in ~1 hour. Get a long-lived token like this:
+
+```
+GET https://graph.facebook.com/v19.0/oauth/access_token
+  ?grant_type=fb_exchange_token
+  &client_id={app-id}
+  &client_secret={app-secret}
+  &fb_exchange_token={short-lived-token}
+```
+
+Then fetch the Page token again using the step above — a Page token generated from a long-lived User token never expires.
+
+#### 4. `FACEBOOK_PAGE_ID`
+
+Found in the Page URL (`facebook.com/mypage`) or under the Page's **About** section → **Page ID**.
+
+---
+
+### LinkedIn — `LINKEDIN_ACCESS_TOKEN` and `LINKEDIN_AUTHOR_URN`
+
+Requirements: a LinkedIn **App** associated with a **LinkedIn Page** or personal account.
+
+#### 1. Create a LinkedIn App
+
+1. Go to the [LinkedIn Developer Portal](https://www.linkedin.com/developers/apps).
+2. Click **Create app**.
+3. Enter the app name and associate it with your LinkedIn Page.
+4. After the app is verified, go to the **Products** tab and request access to **Share on LinkedIn** and **Sign In with LinkedIn using OpenID Connect**.
+
+#### 2. Get an OAuth2 Access Token
+
+Your `Client ID` and `Client Secret` are on the app's **Auth** tab.
+
+Required scopes: `w_member_social` (personal post) or `w_organization_social` (company page).
+
+The easiest way to generate a token is via the [LinkedIn OAuth 2.0 Tools](https://www.linkedin.com/developers/tools/oauth) page:
+
+1. Select your app.
+2. Check the required scopes.
+3. Click **Request access token**.
+4. The token is valid for 60 days — you will need to refresh it after expiry.
+
+#### 3. `LINKEDIN_AUTHOR_URN`
+
+**Personal account:**
+
+```
+GET https://api.linkedin.com/v2/userinfo
+Authorization: Bearer {access_token}
+```
+
+The `sub` field in the response is the person ID. The URN format is `urn:li:person:{sub}`.
+
+**Company / Page:**
+
+```
+GET https://api.linkedin.com/v2/organizationalEntityAcls?q=roleAssignee
+Authorization: Bearer {access_token}
+```
+
+The `organizationalTarget` field in the response contains the organization URN (`urn:li:organization:XXXXX`).