diff --git a/README.md b/README.md
new file mode 100644
index 0000000..d3adb1c
--- /dev/null
+++ b/README.md
@@ -0,0 +1,56 @@
+# Daybook
+
+Daybook is a self-hosted, multi-user **artifact journal**. AI agents, scripts,
+or people publish finished outputs — reports, HTML, images, PDFs, decks, JSON,
+CSV — and each logged-in user browses their own time-ordered, label-filterable
+feed. The core principle: **agents publish content, not files.** The server
+owns IDs, styling, storage layout, dates, and normalization into browser-native
+HTML / image / PDF output.
+
+Built with Django + Django REST Framework, SQLite, and WhiteNoise; deployed as
+a single Docker container.
+
+## Quick start (local development)
+
+```bash
+python -m venv .venv
+.venv/Scripts/python -m pip install -r requirements.txt   # Windows; use .venv/bin on POSIX
+python manage.py migrate
+python manage.py createsuperuser
+python manage.py runserver 127.0.0.1:8001
+```
+
+Then open <http://127.0.0.1:8001/> and log in.
+
+- **Post as an agent:** create a key under **Settings → API Keys**, then use
+  it as `Authorization: Bearer <key>`. Each user can hold several keys (one
+  per agent), each revocable on its own.
+- **Health check / contract:** `GET /api/capabilities`.
+- **Ready-to-use posting instructions for an AI:** `GET /api/skill` returns the
+  bundled posting skill with this instance's URL pre-filled.
+
+## Documentation
+
+| Doc | For |
+|---|---|
+| [`docs/agent_quickstart.md`](docs/agent_quickstart.md) | Shortest path to posting from an agent |
+| [`docs/api.md`](docs/api.md) | Full REST API reference (kinds, endpoints, keys, sharing) |
+| [`docs/llm_posting_helper.md`](docs/llm_posting_helper.md) | Using the bundled `daybook_post.py` helper |
+| [`docs/deployment.md`](docs/deployment.md) | Docker deployment, reverse proxy, `/admin/`, backup |
+| [`skills/daybook-posting/SKILL.md`](skills/daybook-posting/SKILL.md) | The agent-posting skill (also served at `/api/skill`) |
+| [`CHANGELOG.md`](CHANGELOG.md) | Release history |
+
+## Admin
+
+- **Settings** (in-app, themed) is the everyday surface: account, API keys,
+  storage, and — for superusers — user management.
+- **Django admin** at `/admin/` is an operator break-glass tool for raw-data
+  fixes. It requires `is_staff` (the `createsuperuser` account has it). See
+  [`docs/deployment.md`](docs/deployment.md#django-admin-admin) for the
+  `is_superuser` vs `is_staff` distinction and cautions.
+
+## Version
+
+The version is defined once in `daybook_project/__init__.py`, shown on
+**Settings → About**, and reported by `GET /api/capabilities`. Releases are
+git-tagged `vX.Y.Z`.
diff --git a/docs/deployment.md b/docs/deployment.md
index cf83192..c1f6257 100644
--- a/docs/deployment.md
+++ b/docs/deployment.md
@@ -135,6 +135,37 @@ docker compose -f deploy/docker-compose.yml exec daybook python manage.py check
 docker compose -f deploy/docker-compose.yml exec daybook sh
 ```
 
+## Django Admin (`/admin/`)
+
+Daybook ships Django's built-in admin at `/admin/` as an operator
+break-glass tool — for raw-data fixes: reset a password, inspect or delete
+any user's artifacts, adjust a quota, audit or revoke API keys. It is
+separate from the in-app **Settings** area, which is the everyday product
+surface (see the in-app guide / `docs/` for normal use).
+
+**Logging in:** open `/admin/` and sign in with an account that has
+`is_staff = True`. The account you create with `createsuperuser` has it (plus
+full superuser rights). Note the two different admin concepts:
+
+- `is_superuser` — Daybook's *in-app* admin (can reach Settings → Users).
+- `is_staff` — can log into *Django's* `/admin/` site.
+
+The `createsuperuser` account has **both**. A user promoted in-app via
+Settings → Users ("Grant admin access") gets `is_superuser` only — so they
+can administer Daybook through its own UI but **cannot** reach `/admin/`.
+Regular users have neither. To grant someone `/admin/` access, set staff
+explicitly:
+
+```bash
+docker compose -f deploy/docker-compose.yml exec daybook \
+  python manage.py shell -c "from django.contrib.auth.models import User; u=User.objects.get(username='NAME'); u.is_staff=True; u.save()"
+```
+
+**Caution:** the admin edits database rows directly and bypasses app logic —
+e.g. deleting an artifact there does not clean up its files on disk the way
+the app's own delete does. Use it for inspection and targeted fixes, not
+routine management.
+
 ## Backup And Restore
 
 Back up `deploy/data/` — it contains the SQLite database and all artifact
@@ -198,6 +229,7 @@ Caddy:   header_up X-Forwarded-Proto https
 ## Known MVP Constraints
 
 - SQLite is used by default — fine for a single-VM self-hosted deployment.
-- Per-user ingest tokens; no shared/global token.
+- Per-user API keys (multiple per user, individually revocable); no
+  shared/global key.
 - Reader/browser access requires login; feeds are private per user.
 - Manual drag/drop upload and content revisions are deferred.