diff --git a/docs/user-stories.md b/docs/user-stories.md
new file mode 100644
index 0000000..c5c3c20
--- /dev/null
+++ b/docs/user-stories.md
@@ -0,0 +1,125 @@
+# GLVD User Stories
+
+# USER-01
+
+As a user of Garden Linux I want to know about security issues in Garden Linux so I can operate my systems responsibly.
+
+## Acceptance Criteria 
+
+- [ ] The user can query for known CVEs of a list packages
+
+## Additional details
+
+- This does not yet require a nice user interface, an HTTP API is sufficient
+- This does not yet include knowledge about which packages are included in any given Garden Linux image, the user provides a list of package names and versions
+
+# USER-02 (lower prio)
+
+As a user of Garden Linux I want to subscribe to updates on new security issues in the packages I care about.
+
+## Acceptance Criteria 
+
+- [ ] The user can get notifications for new known CVEs affecting their list of packages
+- [ ] The user can unsubscribe from notifications
+
+## Additional details
+
+- This might be implemented in an anonymous way where the user gets a tracking url/rss feed they need to bookmark
+- The backend/db needs to keep track of tracking urls
+- Users might want to subscribe with their email address; this introduces a new class of issues legally (data protection)
+
+# USER-05
+
+As a user of Garden Linux I want to be notified of new CVEs in the Garden Linux patch version I'm using.
+
+## Acceptance Criteria 
+
+- [ ] I can select the Garden Linux version (like 1443.5) I'm using to be notified on new CVEs for that specific version
+- [ ] I get a notification for new patch releases in that version (like 1443.6) so I can upgrade as soon as possible
+- [ ] I can select a Garden Linux major version (like 1443) to be notified on new and fixed CVEs in that version
+
+# USER-06
+
+As a user of Garden Linux I want to be notified of new major versions of Garden Linux so I can plan to upgrade.
+
+# USER-07 (higher prio)
+
+As a user of GLVD I want a simple web interface to work with the service in a convenient way.
+
+## Acceptance Criteria 
+
+- [ ] Features described in the previous user stories can be accessed in a minimal web interface, similar to debian security tracker UI
+
+# USER-08
+
+As a user of GLVD I want a CLI tool to interact with the service.
+
+## Acceptance Criteria 
+
+- [ ] Features described in the previous user stories can be accessed using a command line tool
+
+# USER-09
+
+As a user of Garden Linux (container images) I want to be informed about additional issues installed packages bring.
+
+## Acceptance Criteria 
+
+- [ ] A 'apt install' cli wrapper prints information on additional CVEs introduced by that package
+
+# De-prioritized user stories
+
+# USER-03
+
+As a user of Garden Linux I want to track security issues in any given Garden Linux *image* so I can make an informed decision about needed actions in my system.
+
+## Acceptance Criteria 
+
+- [ ] The user can query for Garden Linux images such as `gardenlinux-gcp-gardener-prod-amd64-1443-5-bfb687a7`
+
+# USER-04
+
+As a user of Garden Linux I want to track security issues that additional packages bring into my image.
+
+## Acceptance Criteria 
+
+- [ ] The user can provide additional packages from the Garden Linux APT repo (in the same release as the image in use)
+
+# GLDEV-01
+
+As a developer of Garden Linux I want to assess the security impact of adding packages to Garden Linux images.
+
+## Acceptance Criteria 
+
+- [ ] I can query individual packages within the Garden Linux APT repo for known CVEs, for package versions included in the available releases
+- [ ] I can use released Garden Linux images as a pre-set and add packages to see what additional CVEs are added with the additional packages
+
+# GLDEV-02
+
+As a developer of Garden Linux I want to add context information on CVE that might be fixed or not applicable to Garden Linux.
+
+## Acceptance Criteria 
+
+- [ ] I can add a text comment to any package version describing in what condition this security issue applies to Garden Linux
+- [ ] I can add new package versions to account for rebuilt and manually patched packages in Garden Linux
+
+# GLDEV-03
+
+As a developer of Garden Linux I want to generate parts of release notes for new patch and major versions of Garden Linux.
+
+## Acceptance Criteria 
+
+- [ ] GLVD can create markdown output that is suitable for adding it to Github releases page
+
+
+
+# Notes from discussion
+
+- Get List of vuln by package name and version
+- Get List of vuln packages by distro
+- Get List of vuln packages by image
+  - needs manifest files from images (package list with version), generated by builder
+- Get List of vuln packages by ocm descriptor (maybe)
+- Get List of vuln packages by CVE id
+- Triage for GL vuln
+  - output ocm (potential issues, immutability, pull/poll, api, ?)
+  - outbut bdba (maybe)