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.
Beacon screenshot 1: owner front door
Beacon screenshot 2: resolution desk
Beacon screenshot 3: evidence review

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.

app.routes.v1app.pages.v1app.navigation.v1app.settings.v1jobs.consumers.v1schedules.cron.v1approval.eligibility.v2conversation.assignment.v1case.assignment.v1case.due-time.v1evidence.requirements.v2ai.review-boundary.v1ai.instructions.v1notification.routing.v1conversation.created.v1conversation.status-changed.v1conversation.merged.v1message.received.v1case.created.v1case.assigned.v1case.status-changed.v1case.escalated.v1case.merged.v1case.linked.v1evidence.collected.v1decision.created.v1approval.requested.v1approval.decided.v1action.submitted.v1action.succeeded.v1action.failed.v1action.indeterminate.v1customer-notification.status-changed.v1case.completed.v1receipt.created.v1import.completed.v1app.navigation.after.v1conversation.list.row-actions.v1conversation.detail.header.after.v1conversation.timeline.after.v1conversation.customer-context.after.v1conversation.linked-cases.after.v1case.detail.header.after.v1case.evidence.after.v1case.decision.after.v1case.actions.after.v1approval.review.after.v1customer.profile.tabs.after.v1resolution.receipt.after.v1settings.sections.after.v1analytics.dashboard.after.v1mail.inbound.v1mail.sender.v1operations.provider.v1ai.provider.v1

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

HOME-001
Owner front door.

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

OPS-001
Granted workspace access.

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.

OPS-002
Workspace administration.

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.

OPS-003
Approval eligibility.

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.

OPS-004
Team inbox membership.

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.

OPS-005
Public sign-in boundary.

Customer and public paths disclose no operator, conversation, case, Tracker, evidence, or approval data until their own route-level identity check succeeds.

OPS-006
Conversation-scoped send grant.

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

CHAN-001
Inbound email.

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.

CHAN-002
Strict email threading.

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.

CHAN-003
Ambiguous email.

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.

CHAN-004
Inbound deduplication.

Repeated delivery of one authenticated provider message ID creates one message and one set of downstream events.

CHAN-005
Reviewed outbound email.

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.

CHAN-006
First-party web-chat inbound.

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.

CHAN-007
Reviewed web-chat outbound.

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.

CHAN-008
Attachment access.

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.

CHAN-009
Message delivery truth.

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.

CHAN-010
Automatic mail.

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.

CHAN-011
Authenticated ingress.

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.

CHAN-012
Chat deduplication.

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.

CHAN-013
Rejected attachments.

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.

CHAN-014
Chat presence.

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.

CHAN-015
Operator-created conversation.

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.

CHAN-016
Channel scope.

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

OUT-001
Outbound message preparation.

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.

OUT-002
Audience and schedule.

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.

OUT-003
Conditional content.

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.

OUT-004
Direct delivery.

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.

OUT-005
Series preparation.

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

WIDGET-001
Embed.

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.

WIDGET-002
Visitor token.

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.

WIDGET-003
Allowed origin.

Every widget request is checked against configured host origins. An unlisted origin receives no conversation, customer, availability, or operator data.

WIDGET-004
Availability and offline capture.

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.

WIDGET-005
Appearance.

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.

WIDGET-006
Public previews.

Messenger and Help Center configuration may show mobile-sized previews. Such a preview is not a native mobile operator application.

CONV14 clauses

CONV-001
Lifecycle.

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.

CONV-002
Transcript.

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.

CONV-003
Primary record and opaque identity.

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.

CONV-004
Queues and assignment.

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.

CONV-005
Priority and snooze.

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.

CONV-006
Customer context.

The conversation detail presents its verified customer, relevant contacts, company relationships, other conversations, and linked cases only to a member authorised for those records.

CONV-007
Replies and internal notes.

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.

CONV-008
AI reply aids.

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.

CONV-009
Search and commands.

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.

CONV-010
Conversation merge.

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.

CONV-011
Workbench.

The operator Inbox presents queue navigation, a conversation list, selected timeline, composer, and customer/context panel as one conversation workbench.

CONV-012
Global destinations.

The operator application exposes distinct destinations for Inbox, AI preparation, knowledge, reports, outbound, and contacts. Navigation changes no work state.

CONV-013
Linked-case detail.

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.

CONV-014
Conversation-scoped reviewed send.

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

CASE-001
Separate records.

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.

CASE-002
Creation.

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.

CASE-003
Lifecycle.

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.

CASE-004
Resolution queues.

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.

CASE-005
Assignment.

A permitted member can assign and reassign a case within its permitted case scope. Policy: case.assignment.v1; default: manual assignment, initially unassigned.

CASE-006
Priority.

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.

CASE-007
Due time.

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-008
Replies and notes.

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.

CASE-009
Waiting.

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.

CASE-010
Explicit completion.

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.

CASE-011
Follow-up after completion.

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.

CASE-012
Case merge.

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.

CASE-013
Views.

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.

CASE-014
Search.

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.

CASE-015
Unread.

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.

CASE-016
Escalation.

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.

CASE-017
Tags.

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.

CASE-018
Additive conversation links.

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.

CASE-019
Customer case.

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.

CASE-020
Back-office 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.

CASE-021
Tracker privacy.

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.

CASE-022
Tracker aggregation and action boundary.

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.

CASE-023
Category configuration.

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

CUST-001
Customer and visitor records.

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.

CUST-002
Customer profile.

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.

CUST-003
Contact matching.

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.

CUST-004
Signed web identity.

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.

CUST-005
Consequential identity basis.

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.

CUST-006
People, companies, and history.

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.

CUST-007
Customer merge.

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.

CUST-008
Customer block.

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.

CUST-009
Verified contact points.

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.

CUST-010
Import and segments.

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

EVID-001
Evidence records.

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.

EVID-002
Source truth.

Provider data and uploaded originals remain distinguishable from AI extraction or summary. AI output alone never verifies evidence.

EVID-003
Collection failure.

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.

EVID-004
Decision snapshot evidence.

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.

EVID-005
Revision invalidation.

Changing cited evidence, knowledge, target, parameter, action, or customer message creates a new decision version and invalidates any pending approval of the superseded version.

EVID-006
Historical integrity.

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.

EVID-007
Evidence pack.

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.

EVID-008
Required evidence.

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

KNOW-001
Knowledge library.

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.

KNOW-002
Policy at event time.

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.

KNOW-003
Private material boundary.

Internal notes, customer messages, account data, security reports, and one-off concessions become reusable knowledge only through an operator-authored saved revision.

KNOW-004
Reply templates.

Operators can create, edit, retire, and insert named templates. Insertion fills a review editor and sends nothing.

KNOW-005
Public Help Center.

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.

KNOW-006
Source hub.

An operator can declare a knowledge source and see enabled, ingesting, stale, failed, or disabled state with the source boundary and last retrieval.

KNOW-007
Content suggestions.

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.

KNOW-008
Library health.

The library identifies stale or failed source material and published revisions needing review; it labels unavailable inputs rather than inventing freshness.

AI18 clauses

AI-001
Requested preparation.

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.

AI-002
Grounding.

Every AI output names the conversation, evidence, customer fields, and knowledge revisions it read. An uncited requested fact is returned as missing, not invented.

AI-003
Recommendation contents.

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-004
No AI authority.

AI cannot send a customer message, approve, execute, merge, complete, verify evidence, change a customer, change knowledge, or change a permission.

AI-005
Triage.

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.

AI-006
Mandatory review.

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.

AI-007
Instructions.

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.

AI-008
Provider failure.

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.

AI-009
Cost.

Every AI call records provider, model, feature, input and output tokens, latency, and estimated cost, and operators can inspect totals by day and feature.

AI-010
Proposal boundary.

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.

AI-011
Untrusted sources.

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.

AI-012
Customer language.

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.

AI-013
Test set and review.

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.

AI-014
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.

AI-015
Performance analysis.

Operators can inspect labelled AI preparation performance and zero-involvement conversations with source and date range; no success-looking chart proves delivery or correctness.

AI-016
Usage guard.

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.

AI-017
Workflow preparation.

Operators can prepare an internal reviewable workflow. It cannot activate an autonomous customer send, external provider mutation, or an extension bypass of JUDG-004.

AI-018
Deferred Fin navigation.

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

JUDG-001
Eligible recommendation.

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.

JUDG-002
Evidence provenance.

Every recommendation fact and citation preserves source identifier, captured value, source version, and retrieval time, viewable by the reviewer.

JUDG-003
Published policy.

An executable recommendation names the exact published knowledge revision and section it applies.

JUDG-004
Human gate.

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.

JUDG-005
Manual resolution.

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.

JUDG-006
Freshness gate.

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.

JUDG-007
Insufficient evidence.

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.

JUDG-008
AI failure boundary.

AI failure retains manual investigation and existing approved work but produces no silent substitute evidence, classification, recommendation, or customer send.

JUDG-009
Instruction boundary.

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.

JUDG-010
Reversibility.

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.

JUDG-011
Named review.

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

APPR-001
Approval request.

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.

APPR-002
Approval queue.

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.

APPR-003
Review.

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.

APPR-004
Decisions.

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.

APPR-005
Return.

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.

APPR-006
Decline.

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.

APPR-007
Single decision.

One decision version accepts one terminal decision. A repeated click or request returns the stored decision and creates no further action.

APPR-008
Approval command.

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.

APPR-009
Approval preconditions.

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

ACT-001
Action adapter.

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.

ACT-002
Idempotency.

Repeated approval clicks, queue retries, Worker restarts, and duplicate provider webhooks refer to the same durable action and never issue a second logical action.

ACT-003
Outcome states.

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.

ACT-004
Indeterminate result.

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.

ACT-005
Reconciliation.

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.

ACT-006
Completion.

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.

ACT-007
Failed action.

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.

ACT-008
Provider claims.

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.

ACT-009
Action eligibility.

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.

ACT-010
Immutable decision snapshot.

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.

ACT-011
Immediate provider preflight.

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.

ACT-012
Execution progress.

A decision shows validation, provider execution, outcome recording, and customer-draft preparation, with start and completion times for each completed step.

ACT-013
Customer-message preparation and send.

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.

ACT-014
One in-flight target.

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.

ACT-015
Conditional mutation.

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.

ACT-016
Execution pause.

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.

ACT-017
Provider outage.

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.

ACT-018
Reversal.

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.

ACT-019
Declared operation boundary.

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

RCPT-001
Receipt creation.

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.

RCPT-002
Action record before completion.

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.

RCPT-003
Customer receipt access.

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.

RCPT-004
Amendments.

Later events never rewrite a receipt snapshot. A late provider or delivery event creates an append-only amendment presented beside the original.

RCPT-005
Per-target ownership.

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

NOTIFY-001
Customer notification truth.

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.

NOTIFY-002
Operator routing.

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.

NOTIFY-003
Quiet hours.

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.

NOTIFY-004
Coalescing.

At most one unread customer-reply alert and one unread approval-needed alert are outstanding per member per case; later matching events update it.

NOTIFY-005
Delivery status.

Every operator alert and customer notification records provider acceptance, delivery where confirmed, bounce, retry, and terminal failure without changing a confirmed provider outcome.

NOTIFY-006
Customer-message failure.

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.

NOTIFY-007
No loops.

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-001
Event-derived metrics.

Analytics derive from immutable conversation, case, decision, action, notification, and feedback events; editing a live record never rewrites an earlier reporting event.

ANALYTICS-002
Conversation and outcome definitions.

Reports distinguish first response, conversation volume, customer message delivery, decisions, approvals, provider-confirmed success, failure, indeterminate outcome, reconciliation, and no-action resolution.

ANALYTICS-003
Filters and drill-down.

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.

ANALYTICS-004
Exports and unavailable metrics.

An operator can export authorised report rows. A zero denominator or missing input is shown unavailable with reason, never fabricated as zero.

ANALYTICS-005
Custom charts.

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.

ANALYTICS-006
Conversation topics.

Operators can review conversation-topic analysis with its source range and model provenance. AI-derived topics remain analysis, not verified customer facts.

SETUP1 clause

SETUP-001
Guided setup.

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

DATA-001
Portable export contents.

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.

DATA-002
Retention after erasure, superseding BASE-DATA-003.

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

IMPORT-001
Intercom export importer.

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.

BASE-DATA-005
Independence.

The deployment makes no request to the marketplace or the seed author. There is no telemetry, phone-home, licence check, or kill switch.

Declared guarantee
BASE-DATA-001
Export and import.

pnpm export produces every record and attachment; pnpm import restores it into an empty deployment; export, import, export yields an archive with equivalent contents.

Declared guarantee
BASE-DATA-004
Outbound flows.

User data leaves the deployment only through externals declared in seed.json → externals. No other outbound request carries user data.

Declared guarantee
BASE-PUBLIC-001
Privacy.

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.

Declared guarantee
BASE-SECRET-001
No leakage.

No secret appears in the client bundle, in logs, or in an error response.

Declared guarantee

BASELINE.md for Beacon


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.

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.

The machine face

Beacon landing screenshot

Run Beacon on your own cloud.

MIT code, your data, your infrastructure. Leave whenever you like and it keeps running.