Seed catalogue · Support
Beacon
A self-hosted conversation desk for a business's customer conversations and separately raised cases.
- Alternative to
- Intercom, under MIT
- Family
- Support
- Edition
- Beacon
- Version
- 0.2.0
- Contract
- 176 clauses across 20 areas
- Maturity
- Stage 2 partial development: HOME-001 and CASE-011 have accepted full-clause evidence; D1-backed channel, notification, customer, receipt, Start, and widget seams have bounded implementation evidence. WIDGET-001–005 client/configuration/contact verification and all other product clauses remain pending full-clause acceptance.



3 screenshots from the product's own visual and verification artifacts. Its handover records what was exercised.
What you get
Everything below is generated from the seed's own manifest and contract. No rounded-off claims, no numbers we made up.
Operating cost
Estimated, not free by default
The seed's own cost declaration, unedited.
- Status
- Unmeasured: local resource use and declared provider pricing/rate bases still need recording; this deployable-only wave does not require a hosted runtime.
Externals declared
3 externals, each with a reason
Under BASE-DATA-004, user data leaves only through what is declared here.
- mail-provider
- An external mail provider receives customer email and delivers email outside the deployment, which owned Cloudflare primitives cannot do.
- operations-provider
- The external provider owns the action target and authoritative outcome, which the deployment cannot reproduce with an owned Cloudflare primitive.
- ai-provider
- A replaceable AI provider performs requested preparation that no owned Cloudflare primitive provides.
Extension points
55 declared integration conveniences
These hooks are optional conveniences. Owners may change any source, including core logic, schema and infrastructure; their agents adapt useful upstream fixes and verify the result.
Declared limits
Capacity, stated up front
Straight from seed.json → limits. Where a value is an estimate the seed says so.
- Status
- Estimated bootstrap rate limits are implemented but unmeasured; capacity limits await a load test.
- Public Requests Per Ip Per Minute
- 60
- Magic Link Requests Per Ip Per15 Minutes
- 20
- Magic Link Requests Per Email Per15 Minutes
- 5
- Magic Link Verification Requests Per Ip Per15 Minutes
- 30
- Inbound Attachment Bytes
- 26,214,400
Non-goals, stated proudly
A product that says what it will never do is a product you can trust to stay small, fast and legible. These are refusals, not gaps.
- SMS and WhatsApp channel adapters are deferred beyond 1.0.
- In-app announcements, mobile push and carousel, product tours and checklists, and surveys are outside 1.0.
- A native mobile operator application is outside 1.0.
- Live autonomous AI replies, customer-message automation, and external-provider automation are outside 1.0.
- Generic workflow and runtime plugin systems are outside 1.0.
- Multiple workspaces or tenants are outside 1.0.
- Help Scout replacement and import are deferred until its report and importer qualify.
The contract
All 176 clauses of Beacon, from its own CONTRACT.md. Stable IDs identify requirements; the source handover and verification evidence distinguish implemented, tested and uncovered behavior.
HOME1 clause
At /, Beacon renders the workspace name and one owner-configured description from src/ext/config.ts, using the configured theme, with a link to /signin. It renders no customer or case data, vendor pricing, feature claims, testimonials, or operational metrics. The configurable “Powered by Beacon · runeditrun.com” credit defaults on; when enabled it is a plain link and makes no request before an operator chooses it.
OPS6 clauses
A signed-in member can read or operate only the inboxes, conversations, cases, and administration grants assigned to them. Every permitted action records the acting member, time, and authorising grant.
A member with workspace-administration grant can configure workspace identity, teammates, teams, channel settings, category configuration, working schedule, and public-channel presentation. Removing the final active workspace administrator is refused with that reason.
A member may approve or submit a manual resolution only when they hold the non-bypassable decide grant for that case type. The decision records the signed-in member and grant. Policy: approval.eligibility.v2; default: permit a qualified preparer to approve their own decision; the policy may impose an additional reviewer condition or forbid self-approval but cannot admit a member without the decide grant.
A routing administrator can create inboxes, give members inbox membership, and select a routing mode. The recorded selection and every assignment preserve the actor and time.
Customer and public paths disclose no operator, conversation, case, Tracker, evidence, or approval data until their own route-level identity check succeeds.
A member may review, approve, or manually resolve a conversation customer send, whether or not that conversation has linked cases, only when they hold the non-bypassable conversation-send grant for its inbox. This grant cannot authorise an external-provider mutation, case action, command, or receipt.
CHAN16 clauses
A signed, configured inbound-mail event becomes one conversation message within 60 seconds, preserving sender, recipients, subject, text and sanitised HTML bodies, attachments, provider message ID, and threading headers.
An inbound reply joins a conversation only when its In-Reply-To or References header names a stored message of that conversation, or its signed Beacon reply token names that conversation.
An inbound email that CHAN-002 does not prove belongs to a conversation starts a new conversation. When its sender is a verified contact point of a known customer, the new conversation links that customer and is flagged as possibly related to that customer's most recent non-completed case. Sender or subject similarity alone never joins it to an existing conversation.
Repeated delivery of one authenticated provider message ID creates one message and one set of downstream events.
A signed-in member may submit an email only from a reviewed case outcome send under ACT-013 or a reviewed conversation-scoped send under CONV-014, whether or not that conversation has linked cases. It is submitted to mail.sender.v1 within 60 seconds with stable delivery ID, correct threading headers, and attachments within declared limits. An email recipient is a verified contact under CUST-009.
A visitor message appends to that visitor's open conversation or starts one and appears to permitted operators within 2 seconds. A visitor has at most one open conversation.
A signed-in member may submit web chat only from a reviewed case outcome send under ACT-013 or a reviewed conversation-scoped send under CONV-014, whether or not that conversation has linked cases. It reaches the authenticated visitor session or token that owns the conversation within two seconds. A disconnected visitor sees it on reconnect, and a customer with a verified email contact receives email fallback within 60 seconds only when the reviewed send permits it.
An accepted attachment keeps its original bytes and declared filename and is readable only by an authorised member, the visitor session that owns its conversation, and an approved delivery to that conversation's verified customer contact. It reaches no other recipient.
Every outbound customer message records queued, sent, delivered, or failed, its attempts, and a redacted provider outcome. For web chat, delivered means the visitor session acknowledged it. A transient submission failure receives at most five attempts over one hour using the same delivery ID; permanent rejection or later bounce is failed and not resubmitted.
Automatic, bulk, list, and no-reply mail is preserved on its conversation but does not reopen it, create a case, alert a member, or invoke AI.
Mail webhooks authenticate through mail.inbound.v1 and external-provider webhooks through operations.provider.v1 before any deduplication or mutation. An absent or invalid signature creates no message, event, action transition, or AI request and is recorded as a rejected delivery.
Each web-chat submission has a visitor-scoped client message ID. A retry returns its stored message and creates no duplicate message, case, alert, or AI request.
An oversized, disallowed, or malformed attachment stores no bytes and appears as a rejected placeholder naming its filename and reason while the rest of the message is preserved.
While web chat is connected, a typing signal from either side reaches the other within two seconds, carries no message text, and clears after 10 seconds without a keystroke. The visitor sees whether Beacon accepted or rejected each own message, and can retry a rejected message under CHAN-012 using its original client message ID.
A permitted member can begin an email or first-party web-chat conversation with a verified customer contact, optionally linking an existing case. It creates no case merely because it is sent or replied to; a member raises any case explicitly under CASE-002.
Beacon's 1.0 customer channels are verified email and first-party web chat. SMS and WhatsApp are deferred adapter families; their absence from 1.0 is not an assertion that an incumbent menu lacks them.
OUT5 clauses
A permitted member can prepare a one-off reviewed outbound email or first-party web-chat message, naming its audience, channel, content, and purpose. Preparation sends nothing and creates no live autonomous campaign.
A reviewed outbound audience rule records its version and evaluation time but only prepares candidates. Before review Beacon resolves a fixed target snapshot. Each target follows exactly one path: a case-specific target has its own case, ACT-010 decision snapshot, JUDG-004 review, approval or manual resolution, delivery record, and receipt where applicable; a conversation-scoped target uses its own CONV-014 immutable per-recipient reviewed-send snapshot, whether or not that conversation has linked cases, and its delivery creates no case, action, command, or receipt. A changed audience rule or membership may create a new fixed target snapshot only before that target is reviewed; it never expands an already reviewed decision or send snapshot.
A reviewed outbound decision may prepare conditional customer-safe content with a named condition and fallback. Each delivered target records the resolved branch; a fallback never fabricates a missing customer attribute.
A reviewed outbound message is delivered only through CHAN-005 or CHAN-007 after its customer-level review decision. It records delivery truth under CHAN-009 and does not become an autonomous send because it was scheduled.
A member can prepare a multi-step outbound Series for review. A Series cannot activate, send a step, call a provider, or bypass per-target customer-send approval until separately declared and implemented in a later contract release.
WIDGET6 clauses
A host page embeds first-party web chat with one asynchronous script tag carrying a workspace key and nothing else. The first script is under 50KB gzipped, does not block host rendering, and every later asset comes from the Beacon deployment.
At first interaction Beacon issues an opaque browser-stored visitor token that restores only that visitor's own conversation history on later loads and grants no operator or customer credential.
Every widget request is checked against configured host origins. An unlisted origin receives no conversation, customer, availability, or operator data.
The widget reports operators present only when a permitted operator has had the app focused within five minutes and the current time falls inside the configured working schedule; otherwise it shows the configured away message and expected first-reply time. The composer accepts messages in both states. An offline message remains a conversation message, asks the visitor for an email contact point to verify under CUST-009, and creates no case until a member chooses case type and reason under CASE-002. The availability request carries workspace key and no visitor token, so it sends no visitor data before first interaction.
Launcher label, accent colour, corner position, welcome message, and away message are workspace settings applied on the next widget load without changing the host embed.
Messenger and Help Center configuration may show mobile-sized previews. Such a preview is not a native mobile operator application.
CONV14 clauses
A conversation is open, snoozed until a recorded time, or closed. A non-automatic customer message reopens a closed or snoozed conversation unless CUST-008 blocks the customer, without altering any linked case, action, or receipt.
An authorised member can prepare a transcript for a verified contact of that conversation's customer. It contains customer-visible messages and times only, never a private note, evidence, decision, or rationale.
A conversation is the customer communication timeline with an opaque internal conversationId; it is not publicly addressed. Its messages, internal notes, channel identity, customer context, assignment, state, and merge history remain on the conversation.
A permitted member can assign, reassign, or unassign a conversation within a granted inbox and can select a queue view. Policy: conversation.assignment.v1; default: manual assignment, initially unassigned.
A member can set a conversation priority and snooze it to a recorded time. Snoozing removes it from active views until the time expires or CONV-001 reopens it; each change is audited.
The conversation detail presents its verified customer, relevant contacts, company relationships, other conversations, and linked cases only to a member authorised for those records.
A member can draft a customer reply or add an internal note. Notes are visually distinct, never leave the deployment, never appear in a customer route, and never enter a customer-facing AI output.
A member may request a cited rewrite, macro-assisted draft, summary, or reply draft. It enters a review surface, is labelled AI where applicable, and cannot send itself.
Permitted members can search and filter conversations and use explicit commands such as assignment, snooze, case creation, and merge. A command records its actor and does not infer a case or external action.
A member with merge grant may merge conversations only when both link the same verified customer. The member selects a canonical conversation and records a reason. The merge emits conversation.merged.v1 naming former and canonical conversation, member, time, and reason. The losing conversation becomes a read-only merge pointer; its messages, notes, source identity, and audit history remain readable only through their original customer authorisation boundary. Every case whose originating conversation becomes non-canonical retains that origin and receives an immutable origin-merge-link audit event naming case, former origin, canonical conversation, member, time, and reason. Cases remain separate and are neither merged nor rewritten.
The operator Inbox presents queue navigation, a conversation list, selected timeline, composer, and customer/context panel as one conversation workbench.
The operator application exposes distinct destinations for Inbox, AI preparation, knowledge, reports, outbound, and contacts. Navigation changes no work state.
A conversation detail lists its originating and additional linked cases, including Customer, Back-office, and Tracker cases available to that member; a link does not turn the conversation into a case.
A conversation may remain at zero cases and may also have linked cases. In either situation a signed-in member holding its conversation-send grant may create an immutable per-recipient reviewed-send snapshot. The snapshot names the conversation, authenticated visitor session/token or verified email recipient, channel, content, actor, review/approval or manual-resolution member, time, and stable delivery ID. It is sent once through CHAN-005 or CHAN-007, records delivery truth under CHAN-009, creates or mutates no case, provider command, case action, or receipt, and a changed recipient or content requires a new snapshot. Email requires CUST-009 verified contact; first-party web chat may target the authenticated visitor session/token that owns the conversation.
CASE23 clauses
A case is separately created accountable work over one required originating conversation. A new conversation starts with zero cases; a conversation may have zero or many cases. A case owns its type, lifecycle, evidence, decision, action, and receipt history.
A permitted member creates a case from a conversation by selecting Customer, Back-office, or Tracker type and recording a reason. Inbound email, operator-created conversation, widget offline capture, or a customer reply never creates a case automatically.
A case is in exactly one of working, waiting, awaiting_approval, returned, declined, executing, action_failed, action_indeterminate, awaiting_message, notification_failed, or completed. Every transition preserves actor or feature, time, and reason. Assignment, priority, escalation, tags, and due time are independent fields that no transition clears.
Every non-completed case appears in exactly one primary queue, selected in this order: an escalation flag or action_failed, action_indeterminate, or notification_failed state is Escalated; awaiting_message is Ready to send; waiting or executing is Waiting; any other non-completed case is Needs a decision. A completed case appears in no primary queue and remains searchable and reportable.
A permitted member can assign and reassign a case within its permitted case scope. Policy: case.assignment.v1; default: manual assignment, initially unassigned.
Each case has low, medium, or high priority and starts at medium. A member can change it, and its recorded reason says whether its current value came from a member or AI-005 suggestion.
Every non-completed case stores a UTC due instant computed from configured IANA workspace timezone, weekly working schedule, and holiday dates, and is labelled due later, due today, or overdue in that timezone. A later schedule change affects only new calculations. Policy: case.due-time.v1; default: four configured working hours from creation.
Case activity may show prepared customer messages and internal notes. A note remains private under CONV-007, and a prepared customer message still requires JUDG-004 and ACT-013 before it is sent.
Moving a case to waiting records a reason and wake time. It returns to working within 60 seconds of wake or immediately on a non-automatic customer message, and each return produces exactly one operator alert under NOTIFY-002.
Approval and provider acceptance never complete a case. An executable-action case completes only after the authoritative provider reports that action succeeded and its required reviewed customer message is recorded sent. A documented no-action resolution may complete a case only when it has no pending, indeterminate, or succeeded action; a failed action remains visible and needs either replacement or the documented permitted no-action resolution. Inactivity and conversation close never complete a case.
A member can create a linked follow-up case after completion. No later customer message creates a follow-up automatically; previous decisions, actions, and receipts remain immutable.
A permitted member may merge two non-completed cases only when they belong to the same customer and have compatible visibility scope; a Tracker case cannot merge with a Customer or Back-office case. The member names a canonical case and records a reason. The losing case becomes a read-only pointer, retains its notes, evidence, decision versions, event history, originating conversation, and links, accepts no new proposal, decision, action, or case link, and cannot expose its private history through the canonical case. The merge emits case.merged.v1 naming both cases, canonical case, member, time, and reason. Case merge is separate from CONV-010 and never erases a source conversation.
Members can list cases by primary queue, lifecycle state, channel, assignee, priority, due state, and tag, sorted by last activity or due time in pages of the size declared in seed.json limits.
Full-text search over customer names and contact points, message bodies, case subjects and identifiers, evidence labels, and receipt references returns authorised matching cases within 500ms.
A case is unread for a member until that member opens it after the latest customer message in its conversation. Every authorised case view shows that member's unread count.
A permitted member can set or clear a durable escalation flag with reason. The flag routes the case to Escalated without changing lifecycle state, assignee, or due time, and alerts the members named by notification.routing.v1.
A permitted member can add and remove named case tags. Tags are filterable under CASE-013, reportable under ANALYTICS-003, and included in an authorised operator export.
A case retains its origin conversation and may receive additional audited related-conversation links. A link is additive: it does not merge conversations, customers, identities, notes, messages, or case histories, and it carries the member, reason, and time.
A Customer case is customer shared and reply capable. It has a stable short public case number; its public route exposes only customer-safe material authorised for that case.
A Back-office case is private by default in 1.0. A later customer-exposure capability requires a new contract clause, release change, permissions model, and customer-safe disclosure rules.
A Tracker case has no public number, public route, customer search result, customer export entry, or customer notification. No setting, policy, extension, import flag, edition, or role grant can make it customer shared.
A Tracker may aggregate related conversations and linked cases for a widespread issue using CASE-018. It never merges customer identities and cannot itself authorise a customer send or provider action. Each customer-specific target has a separate linked Customer or Back-office case with its own origin, target, decision, approval, command, outcome, and receipt.
A routing administrator can configure case states and attributes by case type. Category configuration cannot relax CASE-019, CASE-020, CASE-021, CASE-022, JUDG-004, or provider-outcome rules.
CUST10 clauses
An inbound message from a verified email contact links the unique customer that owns that contact, or creates one customer when no such verified association exists. A web-chat visitor without a verified contact remains an anonymous visitor record; obtaining a verified contact can link it to that customer.
A customer holds name, verified contact points, preferred contact method, relationships, permitted notes, tags, enabled custom fields, conversations, cases, action outcomes, receipts, and audited activity. A permitted member can edit profile fields, and activity records each edit with actor, time, and before/after value.
One verified case-insensitive email contact belongs to exactly one customer, and every inbound conversation from that verified contact links to that customer. A customer-entered unverified contact value neither merges customers nor authorises disclosure.
A host may pass a signed customer identity. An absent or invalid signature leaves the visitor anonymous and exposes no customer history; a valid identity links only the named customer.
A customer-specific decision records the verified contact, signed identity, or operator-recorded verification tying its target to the customer, including method and time. Approval refuses without this basis.
A permitted member can view people, companies, and their relationships. A customer history lists that customer's conversations, cases, action outcomes, receipts, and activity in chronological order without changing primary-record ownership.
A permitted member can merge two customers only after reviewing both identities and histories. The canonical customer receives every linked conversation, case, action outcome, receipt, and permitted profile record; the losing customer becomes an auditable pointer preserving source lineage and both identities. The merge never exposes Tracker content to a customer.
A permitted operator can block or unblock a customer. While blocked, new messages are preserved but create no alert, AI request, automatic state change, or case.
A contact becomes verified only through inbound mail, a valid signed identity, or its owner opening a one-time confirmation link. It records method, time, and actor; unverified contacts receive no case content, receipt link, transcript, or customer delivery.
An operator can import and manage customers, companies, tags, and segments only through IMPORT-001 and declared contact rules; imports cannot infer customer identity from Tracker aggregation.
EVID8 clauses
Each evidence record names type, source system, immutable source identifier, retrieval time, verification state, and requesting case. In every operator presentation card numbers, bank-account numbers, and provider secrets show only their last four characters where shown at all.
Provider data and uploaded originals remain distinguishable from AI extraction or summary. AI output alone never verifies evidence.
Missing, not-found, or errored evidence is shown unavailable with reason and attempt time and is never replaced by generated content. Required unavailable evidence blocks a decision.
A decision snapshot records the customer identity basis, action target and parameters, evidence IDs and verification states, exact knowledge or policy revision and section, proposed customer text, preparer, and rationale reviewed.
Changing cited evidence, knowledge, target, parameter, action, or customer message creates a new decision version and invalidates any pending approval of the superseded version.
Evidence and knowledge revisions cited by a decision remain readable and unchanged after live sources change; a receipt renders from cited versions, subject to DATA-002 anonymisation.
An authorised operator can export a case's permitted messages, evidence metadata and originals, decision versions, outcomes, and receipt as a portable archive without Tracker disclosure to a customer.
Each declared executable operation names the verified evidence required before approval. Policy: evidence.requirements.v2; default: the operation declaration's verified evidence and current identity basis, while no-action requires a documented reason.
KNOW8 clauses
Operators can create, revise, organise, archive, and search structured articles and guidance. A revision has draft, in-review, published, or outdated state and immutable history.
An operational recommendation or decision selects the published knowledge or policy revision effective at the cited transaction or event time, or at case creation when no transaction/event exists, and freezes that exact revision and section into EVID-004 and ACT-010.
Internal notes, customer messages, account data, security reports, and one-off concessions become reusable knowledge only through an operator-authored saved revision.
Operators can create, edit, retire, and insert named templates. Insertion fills a review editor and sends nothing.
Published public articles may appear in a Help Center with customer-safe routes and revision history. It never exposes private notes, Back-office content, Tracker content, decision evidence, or drafts.
An operator can declare a knowledge source and see enabled, ingesting, stale, failed, or disabled state with the source boundary and last retrieval.
AI may prepare a knowledge-content suggestion for operator review. It is not published or used by an assistant until an operator saves and publishes a revision.
The library identifies stale or failed source material and published revisions needing review; it labels unavailable inputs rather than inventing freshness.
AI18 clauses
A member can request a summary, classification, extraction, recommendation, reply draft, or content suggestion. The result is labelled AI, linked to its model call, and neither sent nor acted on.
Every AI output names the conversation, evidence, customer fields, and knowledge revisions it read. An uncited requested fact is returned as missing, not invented.
An actionable recommendation states the proposed operation, target, customer consequence, rationale, confidence, missing evidence, and editable customer text where a message may be needed.
AI cannot send a customer message, approve, execute, merge, complete, verify evidence, change a customer, change knowledge, or change a permission.
When ai.provider.v1 is configured, within 10 seconds of each non-automatic customer message Beacon records exactly one of: a labelled intent, priority suggestion, and EVID-008 checklist; an explicit no-match that changes no case field; or the AI-008 failure record. A member reviews any suggested queue or priority before it changes work state.
A case meeting a mandatory-review trigger is labelled Mandatory review and receives no recommendation until a member asks. On another case whose AI-005 intent names a resolution type, Beacon may prepare one only after required EVID-008 evidence is complete. Neither path lets AI act. Policy: ai.review-boundary.v1; default: no CUST-005 identity basis, a customer request for a human, or an AI intent of security, legal, or account access; an override may add triggers but cannot remove these triggers or the JUDG-004 gate.
Drafts and recommendations follow buyer-authored instructions that never override evidence, policy, source boundary, approval, action, or privacy constraints. Policy: ai.instructions.v1; default: answer concisely from cited case and knowledge sources only.
With ai.provider.v1 unconfigured, AI controls are visibly unavailable and triage is skipped. When a call times out or fails, the member sees the recorded error, the case stays usable, no decision is created, and no other case transition happens.
Every AI call records provider, model, feature, input and output tokens, latency, and estimated cost, and operators can inspect totals by day and feature.
A recommendation becomes a decision only when a signed-in member saves a reviewed immutable ACT-010 decision snapshot. A recommendation identifier is refused wherever a decision version is required, and accepting it records the member who accepted it.
Customer messages, attachments, provider fields, retrieved evidence, and knowledge content are data, never instructions. They cannot widen source access, action permissions, or fields sent through ai.provider.v1.
A customer record stores the language of their messages, detected on first contact and editable by a member. A member sees a labelled translation of a message outside the configured workspace language before deciding; an AI-drafted customer message is written in the customer language. Without ai.provider.v1 the language is member-set and no translation is shown.
Operators can add manual questions, generated questions, or imported CSV questions to an AI test set, and review source, expected answer, rating, and notes before any deployment preparation.
Operators can prepare an AI deployment audience, channel, escalation path, and version for review. Preparation is disabled for live sending or external action until JUDG-004, ACT-011, and channel approvals are satisfied.
Operators can inspect labelled AI preparation performance and zero-involvement conversations with source and date range; no success-looking chart proves delivery or correctness.
A workspace can set usage alerts and a hard limit. At its limit, AI preparation stops and conversations route to permitted teammates; no existing customer message or provider outcome is fabricated.
Operators can prepare an internal reviewable workflow. It cannot activate an autonomous customer send, external provider mutation, or an extension bypass of JUDG-004.
Fin Tasks, Fin Suggestions, and Simple automations are known visible navigation labels whose working workflows are unobserved. They are not 1.0 capability promises and do not appear as active edition functionality.
JUDG11 clauses
A case may have one current recommendation naming a permitted operation or escalation, rationale, customer consequence, risk, confidence, and cited facts. A recommendation is eligible only with its declared evidence and published knowledge.
Every recommendation fact and citation preserves source identifier, captured value, source version, and retrieval time, viewable by the reviewer.
An executable recommendation names the exact published knowledge revision and section it applies.
Beacon sends no customer message until a signed-in member holding either the conversation-send grant for a CONV-014 conversation-scoped send, whether or not that conversation has linked cases, or the case-type decide grant for a case decision approves the reviewed send or submits a manual resolution. Beacon makes no external-provider mutation until a signed-in member holding the case-type decide grant approves the reviewed case decision or submits a manual resolution. No policy, setting, extension, importer, workflow, or edition removes either requirement.
A signed-in eligible member can select a different permitted operation, no-action resolution, or escalation, record an internal reason, and submit a reviewed manual decision. The original recommendation and evidence remain beside it.
If any reviewed decision field, evidence, identity basis, knowledge revision, target, or provider preflight condition changes before approval, approval is refused and the affected fields are named.
A case with missing, conflicting, or ineligible evidence shows its reason and offers only investigation, escalation, or a documented no-action resolution. It presents no executable AI recommendation.
AI failure retains manual investigation and existing approved work but produces no silent substitute evidence, classification, recommendation, or customer send.
Buyer guidance can alter preparation wording or permitted source selection only through AI-007; it cannot relax JUDG-002, JUDG-004, JUDG-006, or EVID-008.
A recommendation or manual decision states whether its declared provider operation is reversible and names the reversal operation where one exists. An irreversible operation is labelled wherever it can be approved.
The review surface shows the case type, customer identity basis, action target, evidence, knowledge, proposed text, decision version, and approving member so a reviewer can reject or return it before action.
APPR9 clauses
A request is created only for a stored current decision version meeting EVID-008 and CUST-005. It names the case, target, operation, requester, reviewers, and requested time.
Approval requests are listed by case lifecycle state—awaiting_approval, returned, declined, executing, action_failed, action_indeterminate, awaiting_message, notification_failed, or completed—with due state and assignee; every row links to the exact decision version reviewed.
The eligible reviewer sees the complete EVID-004 snapshot, including exact policy section, and can open every cited source before deciding. The surface identifies preparer, reviewer, and decision version.
An eligible reviewer can approve, return for changes, or decline. Return and decline require a reason, and every decision records the deciding member and time.
Returning a decision moves the case to returned, preserves the reviewed snapshot and reason, and requires a new decision version before approval can be requested again.
Declining a decision preserves the reviewed snapshot and reason, moves the case to declined, sends no provider command or customer message, and leaves the case for a member to re-propose or complete only under CASE-010.
One decision version accepts one terminal decision. A repeated click or request returns the stored decision and creates no further action.
Once APPR-009 succeeds for an executable provider operation, approval atomically stores the decision, moves the case to executing, and creates exactly one durable provider command for that decision. A documented no-action decision atomically stores its decision and creates no provider command. Neither is provider execution, customer delivery, or case completion.
Immediately before approval Beacon refetches and revalidates case state, current decision version, case-type decide grant, policy eligibility, CUST-005 identity basis, and cited evidence versions and verification states. An executable provider operation requires ACT-009 eligibility and ACT-011 provider preflight. A documented no-action requires CASE-010 guards and EVID-008 evidence, but no provider state or provider preflight. An unavailable required authoritative state or mismatch returns a conflict, audits the rejected attempt, and stores neither decision nor command.
ACT19 clauses
A declared external operation executes through operations.provider.v1 with target, parameters, reason, and Beacon idempotency key. A concrete operation is executable only when ACT-009 and ACT-011 admit it.
Repeated approval clicks, queue retries, Worker restarts, and duplicate provider webhooks refer to the same durable action and never issue a second logical action.
An action is in exactly one of pending, succeeded, failed, or indeterminate and records redacted provider request and outcome fields, provider event IDs, and reconciliation attempts.
A timeout, lost connection, or ambiguous provider response makes the action indeterminate and blocks further mutation on its target until ACT-005 establishes whether the original command took effect.
Provider events and scheduled status checks update an action idempotently. The scheduled check runs at least every 15 minutes on a pending or indeterminate action for up to seven days; a late authoritative success or failure updates that same action and case. An action unresolved after seven days becomes indeterminate if pending, stops being checked, and alerts the responsible member and assignee for manual reconciliation.
Approval and provider acceptance do not complete a case. An executable-action case reaches completed only after operations.provider.v1 reports the action succeeded and its required reviewed customer message is recorded sent. Failed or indeterminate actions cannot complete a case; documented no-action completion remains governed by CASE-010.
A definitively failed action retains its decision and can be replaced only by a new decision that records it and carries a new idempotency key. An indeterminate action blocks replacement until reconciled.
Beacon shows an arrival estimate, destination confirmation, external reference, or outcome detail only when the authoritative provider supplied it, and labels unavailable information as pending or unknown.
An operation must match EVID-008 required evidence, current identity basis, target, parameter constraints, and authoritative provider conditions; a change refuses approval or command submission.
A submitted decision snapshots exactly the case, customer identity basis, actor, operation, parameters, action target, customer consequence, evidence IDs and states, exact knowledge or policy revision and section, and submission time. It cannot be edited or cancelled.
Immediately before command submission, Beacon reads current authoritative provider state and refuses unless target, customer identity, operation, parameters, and declared conflict conditions still match the decision. The command carries the current provider version or equivalent precondition.
A decision shows validation, provider execution, outcome recording, and customer-draft preparation, with start and completion times for each completed step.
A confirmed or documented outcome can prepare customer text stating only what authoritative outcome permits and labelling uncertainty. It never sends itself. A signed-in member reviews and approves or manually resolves the send under JUDG-004; only then may CHAN-005 or CHAN-007 deliver it.
At most one decision for a case and action target is validating or executing at a time. A second approval returns the existing state rather than starting another attempt.
An operation whose adapter cannot provide a current-version or equivalent conditional mutation is never executable; it is offered only as escalation or manual investigation.
An authorised member can pause external execution for the deployment. Intake, review, and approvals remain available, but no provider command is sent; resumption revalidates each command under ACT-011.
When an operations provider cannot read or preflight, Beacon names the outage, refuses provider-action approval, and preserves intake, manual investigation, and no-action resolution. It never queues an unpreflighted mutation as if ready.
A provider-declared reversible action is reversed only by a new case and new decision naming the original decision. Original snapshots and receipts remain immutable and linked.
An executable operation declares its provider adapter, target shape, identity precondition, required evidence, reversibility, and receipt shape. Beacon does not invent a generic provider adapter or operation from a UI field.
RCPT5 clauses
A receipt is created only when CASE-010 permits completed resolution. It is immutable and holds customer and public-case references where applicable, completion basis, acting member and time, exact evidence and knowledge/policy IDs, declared action parameters including amount and currency when financial, action target, authoritative outcome, required customer-message body and delivery state, and chronological activity. A pending or failed delivery remains an operational action view, not a completed-resolution receipt; a documented no-action receipt names its reason.
Before CASE-010 completion an authorised member sees an action or outcome-progress record labelled approved, executing, pending, succeeded, failed, indeterminate, or reconciled as applicable. It is not a completed-resolution receipt. A completed receipt is created only under RCPT-001 and may receive append-only amendments under RCPT-004; approval, submission, and provider acceptance are never success.
An authorised member can view and download a receipt from its case and the customer history. A Customer-case customer receives one signed link to one redacted receipt that expires 30 days after issue and then returns an expired page with no receipt content. The receipt excludes internal notes, Back-office material, Tracker material, private evidence, and operator rationale.
Later events never rewrite a receipt snapshot. A late provider or delivery event creates an append-only amendment presented beside the original.
A receipt belongs to one case and one declared action target. Tracker aggregation cannot create a group receipt or allow one decision receipt to cover unstated customers or targets.
NOTIFY7 clauses
A case outcome notification is sent only under JUDG-004 and ACT-013 and states only the authoritative or documented outcome permitted for its case and target. An ordinary conversation-scoped customer send is sent only under JUDG-004 and CONV-014, whether or not its conversation has linked cases; it is a reviewed conversation delivery, not a case outcome, action, command, or receipt.
Case creation, assignment, escalation, approval request, return, failure, indeterminate outcome, and delivery failure notify authorised members. Policy: notification.routing.v1; default: conversation or case assignee, otherwise approving member, otherwise eligible operators.
Configured quiet hours hold routine email alerts until the next working period while failure and indeterminate-outcome alerts send immediately. In-app alerts are not held.
At most one unread customer-reply alert and one unread approval-needed alert are outstanding per member per case; later matching events update it.
Every operator alert and customer notification records provider acceptance, delivery where confirmed, bounce, retry, and terminal failure without changing a confirmed provider outcome.
A failed required customer message moves the case to notification_failed, preserves the action outcome, and alerts the responsible operator until reviewed delivery is resolved.
Operator notifications, receipt links, transcripts, and optional customer notices use a no-reply address distinct from the support address. Mail to it creates no conversation, case, alert, or AI request.
ANALYTICS6 clauses
Analytics derive from immutable conversation, case, decision, action, notification, and feedback events; editing a live record never rewrites an earlier reporting event.
Reports distinguish first response, conversation volume, customer message delivery, decisions, approvals, provider-confirmed success, failure, indeterminate outcome, reconciliation, and no-action resolution.
A report names its date range, workspace timezone, completion watermark, and filters. Each aggregate drills into the authorised source conversations, cases, or actions it counted.
An operator can export authorised report rows. A zero denominator or missing input is shown unavailable with reason, never fabricated as zero.
Operators can prepare saved report charts from declared event dimensions and measures. A chart does not expose Tracker data to a customer or change operational truth.
Operators can review conversation-topic analysis with its source range and model provenance. AI-derived topics remain analysis, not verified customer facts.
SETUP1 clause
A workspace can present a setup path for sign-in, teammate grants, inboxes, verified channels, widget origins, knowledge, provider adapters, and deployment checks. It labels unconfigured steps rather than claiming readiness.
DATA2 clauses
An authorised operator export contains every permitted customer, visitor, conversation, message, case, tag, evidence, knowledge revision, decision, approval, action, provider event, receipt, notification, setting, and audit entry, plus permitted attachment originals.
Erasing a customer removes their conversations, messages, attachments, evidence originals, and profile under the baseline five-minute cascade, and retains every approval, action, provider event, and receipt with customer reference, message bodies, and contact points anonymised because the business must prove completed operations. The erasure confirmation names what remains and why. The rest of BASE-DATA-003, including its cascade and confirmation, applies unchanged.
IMPORT1 clause
Beacon has one 1.0 importer: Intercom export import. It reads a real Intercom export and declares supported entities, links, attachment treatment, source-ID/timestamp/visibility/history preservation, deterministic idempotency, rejected-record diagnostics, and truthful unsupported-data handling before it imports. It never activates a live Fin reply, workflow, outbound send, provider mutation, public sharing, or Tracker disclosure from source data. Real export proof and implementation are Stage 2 work.
Baseline guarantees
22 declared clauses from this product's BASELINE.md. Selected ownership guarantees are shown below; execution evidence is separate.
The deployment makes no request to the marketplace or the seed author. There is no telemetry, phone-home, licence check, or kill switch.
pnpm export produces every record and attachment; pnpm import restores it into an empty deployment; export, import, export yields an archive with equivalent contents.
User data leaves the deployment only through externals declared in seed.json → externals. No other outbound request carries user data.
Public surfaces (widgets, booking pages, forms, status pages) set no cookies, load nothing from third-party domains, and send no visitor data before the visitor's first interaction.
No secret appears in the client bundle, in logs, or in an error response.
Release history
Honest version: there is one release line so far, and we will not invent the rest.
- v0.2.0
- Current — Stage 2 partial development: HOME-001 and CASE-011 have accepted full-clause evidence; D1-backed channel, notification, customer, receipt, Start, and widget seams have bounded implementation evidence. WIDGET-001–005 client/configuration/contact verification and all other product clauses remain pending full-clause acceptance.
The manifest states this version and maturity. Consult the source verification evidence before deployment.
DIY quickstart
The code is MIT and the deployment is yours. Nothing below talks to us; optional management remains planned.
Use the edition's source README for its available installation commands and required configuration.
View as agent
Everything on this page exists as machine-readable files. If you are an agent evaluating Beacon for someone, read these instead of the prose.
Installation instructions are in the source README; this entry does not declare a catalogue install command.
- README.md
- Source setup, available commands and implementation status.
- seed.json
- The manifest: capabilities mapped to clauses, externals, extension points, limits, operating cost, deploy requirements.
- CONTRACT.md
- The 176 clauses above, in source form.
- BASELINE.md
- The product's declared baseline requirements.
- AGENTS.md
- Instructions written for the coding agent that will maintain this deployment.
- /llms.txt
- The site, for machines.
Catalogue endpoint
/agents/catalogue.json
Every seed with its id, category, version, clause count, install command and links to the files on the left. Generated from the seeds' own artifacts on every build, so it cannot drift from what ships.
Run Beacon on your own cloud.
MIT code, your data, your infrastructure. Leave whenever you like and it keeps running.