docs: improve the README

1 files changed, 28 insertions, 7 deletions

diff --git a/README.md b/README.md
index 48df7d7..73de284 100644
--- a/README.md
+++ b/README.md
@@ -1,14 +1,35 @@
-# sparkled
+# ✨ SparkleLab
 
-This is a web application that allows you to say nice things about other people
-called "Sparkles".
+**Sparkle your colleagues with praise.**
+A low-stakes experiment with high-value learnings.
 
-A single HTML file can be found in `./public/index.html` that is the home page
-for the web application.
+## What's SparkleLab?
+
+SparkleLab is a lightweight service designed to explore modern access control models within GitLab, while doing something fun: helping GitLab team members show appreciation for each other.
+
+We're using this as a **safe space for architectural experimentation**. By integrating with real systems and encouraging real usage, we can validate assumptions, uncover edge cases, and collect meaningful data - all while spreading positivity.
+
+## Why SparkleLab?
+
+The Authorization team is researching ways to evolve GitLab's authorization stack. We need a real, functioning service that:
+
+- Integrates with GitLab
+- Encourages real-world usage and feedback
+- Lets us model and experiment with **RBAC**, **ABAC**, and **ReBAC**
+
+## Key Use Cases
+
+- **Machine-to-Machine** Integrates with Slack via a [slash command](https://api.slack.com/interactivity/slash-commands) to explore how external services can interact with GitLab-managed services.
+- **User-to-User** Authenticates GitLab team members via our OIDC Identity Provider. We'll simulate different access control scenarios (RBAC, ABAC, ReBAC) by adding artificial constraints on who can send praise - even though in reality, *everyone can contribute*.
+
+## Learn More
+
+- [Authorization Design Doc](https://gitlab.com/gitlab-org/architecture/auth-architecture/design-doc)
+- [GitLab Handbook: Say Thanks](https://handbook.gitlab.com/handbook/communication/#say-thanks)
 
 ## Getting Started
 
 ```bash
-  mise install
-  go run ./cmd/sparkled/main.go
+mise install
+go run ./cmd/sparkled/main.go
 ```