feat: init

README.md

@@ -0,0 +1,33 @@
+# almanac
+
+## Context
+
+### Problem
+
+* The recipe catalogue is big and getting bigger. Cloning it locally when
+  running the first commands with `abra` is now becoming *super* slow. Parsing
+  versions and doing on-the-fly catalogue operations in `abra` is getting
+  slower, and slower.
+* It would be better if `abra` didn't even have catalogue management
+  functionality and simply was a "catalogue client" and not also producer. This
+  reduces the scope of `abra` further which has benefits.
+* We need less manual work and more automation to support us so that our
+  project remains sustainable as it scales out horizontally (more collectives,
+  more recipes, more activity).
+* It would be simpler to have automation which doesn't rely on a [relatively
+  complex CI/CD setup](https://git.coopcloud.tech/toolshed/organising/issues/604#issuecomment-20279)
+
+### Proposal
+
+* Use a web API instead of a monolithic Git repository. ([`#604`](https://git.coopcloud.tech/toolshed/organising/issues/604))
+* Make `abra` faster again by making the API fast.
+* Make it fully configurable via the `abra.yml` so everyone can run their own.
+* Re-use the `abra catalogue sync` command to maintain `--offline` support.
+
+## Design goals
+
+* Single binary GUI-less web API
+* Minimal configuration: point it at a Gitea organsation and you're done
+* Webhook API for on-demand catalogue generation
+* Background scheduler for periodic catalogue generation
+* Optimized recipe API for `abra` queries (auto-completion, recipe versions, etc.)