From 59df17a7ce6d5a68f2df09bbb3e7d03370481aec Mon Sep 17 00:00:00 2001
From: Graham Barber <did:plc:57od6g2ic3e3b3kauctjmo3k>
Date: Wed, 18 Mar 2026 00:24:47 -0700
Subject: [PATCH] update README with design clarifications

---
 .gitignore |  2 ++
 README.md  | 45 +++++++++++++++++++++++++++++++--------------
 2 files changed, 33 insertions(+), 14 deletions(-)

diff --git a/.gitignore b/.gitignore
index 08b2553..3c72f8b 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1 +1,3 @@
 node_modules
+
+.claude/settings.local.json
diff --git a/README.md b/README.md
index bbcbb7f..a86c207 100644
--- a/README.md
+++ b/README.md
@@ -4,9 +4,11 @@ Lure is a library for processing webhook events into LLM-consumable prompts. It
 looks something like this:
 
 1. An HTTP request is received at a path like `/webhooks/tangled`
-2. Lure matches the path to a template file on disk, e.g.
-   `./lures/tangled.lure`. The `.lure` file is part config, part template (more
-   on this later).
+2. Lure strips the configured base path and matches the remainder to a template
+   file on disk, e.g. with base path `/webhooks`, the path `/webhooks/tangled`
+   matches `./lures/tangled.lure`. Nested paths are supported: `/webhooks/github/push`
+   matches `./lures/github/push.lure`. The `.lure` file is part config, part
+   template (more on this later).
 3. According to the config, Lure validates the webhook according to the
    specified strategy (e.g. API key or HMAC verification)
 4. If validation succeeds, Lure executes some callback with the string result of
@@ -24,7 +26,6 @@ Markdown file with frontmatter. Here is a contrived example:
 
 ```md
 ---
-register: manual
 verify:
   hmac:
     location: header
@@ -32,21 +33,30 @@ verify:
     secret: $MY_WEBHOOK_SECRET
 payload:
   contentType: json
-  schema: https://example.com/schema
 config:
   arbitrary: true
   someValue: 3
 ---
 
-You have received information about a <%= it.payload.event => event on My
+You have received information about a <%= it.payload.event %> event on My
 Service. Read the following payload and respond according to your skills:
 
 <%= it.payload.body %>
 ```
 
-Different registration and verification methods can be supported, for generic
-implementations or vendor-specific requirements. Only one verification method
-can be specified per lure.
+Different verification methods can be supported, for generic implementations or
+vendor-specific requirements. Only one verification method can be specified per
+lure.
+
+### Template scope
+
+Templates are evaluated using [eta](https://eta.js.org). The following
+properties are available on `it`:
+
+- `it.payload`: The request body. For `contentType: json`, this is the parsed
+  JSON value.
+- `it.headers`: The request headers as a [`Headers`](https://developer.mozilla.org/en-US/docs/Web/API/Headers) object.
+- `it.query`: The query string parameters as a [`URLSearchParams`](https://developer.mozilla.org/en-US/docs/Web/API/URLSearchParams) object.
 
 ## Usage
 
@@ -55,12 +65,17 @@ endpoint handler that suits your HTTP server of choice.
 
 Both handler constructors take the following parameters:
 
+- `basePath`: The URL path prefix under which all lure endpoints are mounted,
+  e.g. `/webhooks`. Lure only handles requests whose path begins with this
+  prefix; all other requests are passed through.
 - `configSchema`: A Standard Schema for validating any extra config you would
   like to allow in the `config` frontmatter key
 - `luresDir`: A path to a directory of lures
 - `callback`: A function that you want to run in response to incoming webhooks.
   It will be called with the templated prompt `prompt` and the value of the
   `config` frontmatter value.
+- `maxAttempts`: How many times to attempt the `callback` before giving up.
+  Defaults to `1` (no retries). If all attempts fail, the webhook is dropped.
 
 ## Lifecycle
 
@@ -77,10 +92,12 @@ Both handler constructors take the following parameters:
 1. The requested path is checked against registered lure paths. 
 2. On a hit, we immediately return a 204 response, to keep the response
    time as low as possible.
-3. Webhook requests are copied and added to a queue for processing.
-3. The queue processor removes requests from the queue FIFO. If verification
+3. Webhook requests are copied and added to an in-memory queue for processing.
+   Requests in the queue will be lost if the process exits.
+4. The queue processor removes requests from the queue FIFO. If verification
    fails, the request is dropped.
-4. On successful verification, the lure template is evaluated using the
+5. On successful verification, the lure template is evaluated using the
    request.
-5. Finally, the provided `callback` is executed with the fully-formed prompt,
-   and the config object from the original `.lure` frontmatter.
+6. The provided `callback` is executed with the fully-formed prompt and the
+   config object from the original `.lure` frontmatter. If the callback throws,
+   it will be retried up to `maxAttempts` times before the webhook is dropped.
-- 
2.51.2