commit 7493e0e941f509a7cb1c57d30fe4941c123cc1cd
Author: decentral1se <cellarspoon@riseup.net>
Date:   Mon Sep 29 11:18:52 2025 +0200

    feat: init

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..595e15e
--- /dev/null
+++ b/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.)