From d4d554205a5236ef9aee4a05ed0666ecc0705242 Mon Sep 17 00:00:00 2001
From: alexion <contact@alexion.dev>
Date: Wed, 2 Sep 2026 08:06:27 -0400
Subject: [PATCH] docs(machoke): add public surface note

---
 docs/02 notes/falinks public surfaces.md |  2 +-
 docs/02 notes/machoke public surface.md  | 46 ++++++++++++++++++++++++
 docs/03 wrk/machoke.md                   | 14 ++++++++
 3 files changed, 61 insertions(+), 1 deletion(-)
 create mode 100644 docs/02 notes/machoke public surface.md
 create mode 100644 docs/03 wrk/machoke.md

diff --git a/docs/02 notes/falinks public surfaces.md b/docs/02 notes/falinks public surfaces.md
index 94b2be9..c75947b 100644
--- a/docs/02 notes/falinks public surfaces.md	
+++ b/docs/02 notes/falinks public surfaces.md	
@@ -4,7 +4,7 @@ date-created: 2026-08-31 21:32
 
 # Falinks Public Surfaces
 
-The project has three components:
+The project has two components:
 - `Falinks`: the library to resolve short links to fully qualified domain names.
 - `falinks` cli:
     - Non-interactive (use for one off requests or by agents)
diff --git a/docs/02 notes/machoke public surface.md b/docs/02 notes/machoke public surface.md
new file mode 100644
index 0000000..ec7f72b
--- /dev/null
+++ b/docs/02 notes/machoke public surface.md	
@@ -0,0 +1,46 @@
+---
+date-created: 2026-09-01 20:17
+---
+
+# Machoke Public Surface
+
+Machoke's primary goal is to be a common storage interface for different types of storage backends.
+
+The first Machoke user is [[falinks|Falinks]]. Its storage needs are simple.
+It just manages a flat list of keyed entries.
+
+The first backend for Machoke is just going to be a simple in-memory map that gets serialized on shutdown and loaded on startup.
+
+## Design
+
+### `Machoke` public interface
+
+| Method          | Parameters              | Returns          | Description                                          |
+| --------------- | ----------------------- | ---------------- | ---------------------------------------------------- |
+| `<constructor>` | `machoke::Options`      | `Result<Machoke<T>>`        | Creates the `Machoke` object.                        |
+| `get`           | `key: String`           | `Result<T>`      | Returns the stored value for the `key` if it exists. |
+| `set`           | `key: String, value: T` | `Result<()>`     | Stores the value using `key`.                        |
+| `delete`        | `key: String`           | `Result<bool>`   | Deletes the value if it exists for `key`.            |
+| `list`          |                         | `Result<Vec<machoke::Entry<T>>>` | Retrieves all stored, raw values.                    |
+
+
+#### machoke::Options
+
+| Key | Type | Default | Description |
+| --- | --- | --- | --- |
+| `backend` | `Backend` | `Backend::Simple` | The storage backend to use. |
+| `path` | `std::path::PathBuf` | tbd | The path to the file/directory for the backend to use. |
+
+
+#### machoke::Entry
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `key` | `String` | The entry key. |
+| `value` | `T` | The stored value. |
+
+#### machoke::Error
+
+- `NotFound`: no value exists for the provided key.
+- `InvalidKey`: the provided key cannot be used.
+- `Backend`: the storage backend failed.
diff --git a/docs/03 wrk/machoke.md b/docs/03 wrk/machoke.md
new file mode 100644
index 0000000..3f8ad39
--- /dev/null
+++ b/docs/03 wrk/machoke.md	
@@ -0,0 +1,14 @@
+---
+date-created: 2026-09-01 20:17
+---
+
+# Machoke
+
+## Current focus
+
+Implement the simple backend.
+
+## References
+
+- [[machoke public surface]]
+- [[falinks public surfaces]]