From e8af67c813ad74fef1c54f834301de3ac1d8417a Mon Sep 17 00:00:00 2001
From: Trevor Slocum <trevor@rocketnine.space>
Date: Mon, 9 Nov 2020 13:59:30 -0800
Subject: [PATCH] Add proposals doc

---
 CONFIGURATION.md |  2 +-
 PROPOSALS.md     | 44 ++++++++++++++++++++++++++++++++++++++++++++
 README.md        |  4 ++++
 3 files changed, 49 insertions(+), 1 deletion(-)
 create mode 100644 PROPOSALS.md

diff --git a/CONFIGURATION.md b/CONFIGURATION.md
index 5d28f71..262f73b 100644
--- a/CONFIGURATION.md
+++ b/CONFIGURATION.md
@@ -135,7 +135,7 @@ may configure twins to send standard `\n` (LF) line endings by setting
 References:
 [1](https://lists.orbitalfox.eu/archives/gemini/2019/000131.html)
 [2](https://lists.orbitalfox.eu/archives/gemini/2020/000756.html)
-[3](https://lists.orbitalfox.eu/archives/gemini/2020/001339.html) 
+[3](https://lists.orbitalfox.eu/archives/gemini/2020/001339.html)
 [4](https://lists.orbitalfox.eu/archives/gemini/2020/003065.html)
 
 # Example config.yaml
diff --git a/PROPOSALS.md b/PROPOSALS.md
new file mode 100644
index 0000000..9a7dde4
--- /dev/null
+++ b/PROPOSALS.md
@@ -0,0 +1,44 @@
+This page is also available at [gemini://twins.rocketnine.space/proposals.gmi](gemini://twins.rocketnine.space/proposals.gmi)
+
+The following proposals add fields to the response header of successful
+requests.
+
+Standard successful response header (for comparison):
+
+```
+20 text/gemini; charset=utf-8
+```
+
+These additions are backwards-compatible as specified in [RFC 2045](https://tools.ietf.org/html/rfc2045):
+
+> MIME implementations must ignore any parameters whose names they do not recognize.
+
+The terms MAY, SHOULD and SHOULD NOT are defined in [RFC 2119](https://tools.ietf.org/html/rfc2119).
+
+# Size
+
+Gemini servers SHOULD include the size (in bytes) of the response body when the
+request is successful. Clients SHOULD utilize this information when downloading
+files to indicate progress.
+
+```
+20 text/gemini; charset=utf-8; size=1108
+```
+
+# Cache
+
+Gemini servers MAY include a duration (in seconds) which a client SHOULD cache
+a resource when the request is successful. When a cache duration of 0 or
+less is provided, clients SHOULD NOT cache the resource.
+
+Cache for one week:
+
+```
+20 text/gemini; charset=utf-8; cache=604800
+```
+
+Do not cache:
+
+```
+20 text/gemini; charset=utf-8; cache=0
+```
diff --git a/README.md b/README.md
index 57217c7..36781ad 100644
--- a/README.md
+++ b/README.md
@@ -19,6 +19,10 @@ This page is also available at [gemini://twins.rocketnine.space](gemini://twins.
 - Serve system command output
 - Reload configuration on `SIGHUP`
 
+## Proposals
+
+twins includes features that are not yet part of the Gemini specification. See [PROPOSALS.md](https://gitlab.com/tslocum/twins/blob/master/PROPOSALS.md)
+
 ## Download
 
 ```bash