From ef2c504a3771eb5c79295d470a65133b0099aa3a Mon Sep 17 00:00:00 2001
From: Madeline <46743919+MaddyUnderStars@users.noreply.github.com>
Date: Fri, 12 May 2023 22:57:34 +1000
Subject: [PATCH] well-known stuff

---
 docs/contributing/instances.md |  2 ++
 docs/setup/server/wellknown.md | 13 +++++++++++++
 2 files changed, 15 insertions(+)
 create mode 100644 docs/setup/server/wellknown.md

diff --git a/docs/contributing/instances.md b/docs/contributing/instances.md
index 8d4b4d1..18d451a 100644
--- a/docs/contributing/instances.md
+++ b/docs/contributing/instances.md
@@ -21,3 +21,5 @@ We recommend (not required) that you:
 -   Run your instance under [SystemD](/setup/server/systemd) or a similar system in your distro, for automatic restarting
 -   Provide some mechanism for users to report content. This may be as simple as more openly advertising your correspondence email (i.e. outside `GET /api/policies/instance` or `/api/ping`)
 -   Provide some mechanism for instance status, such as [Grafana](https://grafana.com/).
+-   Host a [`/.well-known/spacebar`](/setup/server/wellknown) file on the domain you wish users associate with your instance, e.g. `spacebar.chat`.
+	If doing so, use this domain as the `url` field in your community instances PR.
\ No newline at end of file
diff --git a/docs/setup/server/wellknown.md b/docs/setup/server/wellknown.md
new file mode 100644
index 0000000..8342fdf
--- /dev/null
+++ b/docs/setup/server/wellknown.md
@@ -0,0 +1,13 @@
+# well-known
+
+Instance owners may host a `/.well-known/spacebar` file on a domain containing the instance's API endpoint for Spacebar instance discovery.
+
+Users can enter a domain, e.g. `spacebar.chat` as shorthand, and their client will query `https://spacebar.chat/.well-known/spacebar` for the instance API URL,
+and from there the Gateway and CDN endpoints.
+
+Example `/.well-known/spacebar` file:
+```json
+{
+	"api": "https://api.spacebar.chat/api/v9"
+}
+```
\ No newline at end of file