# Opscend — the house email shells
# Instructions for an agent composing an email.
#
# Self-contained on purpose. Everything needed to produce a correct branded
# Opscend email is in this file; you do not need the repository.
#
#   Fetch:  https://<host>/reports    reports@opscend.net
#           https://<host>/hello      hello@opscend.net
#           https://<host>/marcel     marcel@opscend.net
#           https://<host>/no-reply   no-reply@opscend.net
#           https://<host>/agent.txt  (this file)

## 1 · Pick the shell — by the ALIAS the email sends from

REPORTS — reports@opscend.net. A client receiving their reporting from Opscend.
  Opscend-branded for every client: Opscend is visibly the reporting vendor,
  and the client's name is a fact in the docket band, not a rebrand. Compact
  masthead, a docket that answers which client and which period, a well that
  styles tables, and one acid button to the live report.
  Relationship content — NO postal address, NO unsubscribe. That is correct.

HELLO — hello@opscend.net. A person writing to a person. Outreach, onboarding,
  a reply to an enquiry, an announcement. Full centred lockup, and it signs off
  with a named human because mail from hello@ that nobody signed is mail from a
  company. THIS IS COMMERCIAL EMAIL: the postal address and the opt-out are
  REQUIRED and the renderer refuses without them.

MARCEL — marcel@opscend.net. Marcel, personally. One person, always. NOT the
  same as hello@: hello@ is the company's human-facing mailbox that anyone on
  the team can send and that signs with whoever wrote it; this one is signed
  before it is written.
  NO MASTHEAD AT ALL, and that is the design, not an omission. The name is
  already on the envelope, so a wordmark says it a second time — and a 44px
  lockup above a note that opens "Aaron, quick thought" is the exact tell that
  a machine wrote it. The copy starts at the top of the sheet. The brand
  appears once, as an 8px acid square beside the signature.
  ⚠ IT IS TWO THINGS IN LAW AND YOU MUST SAY WHICH — see purpose, below.

NO-REPLY — no-reply@opscend.net. A machine talking to a person. Sign-in codes,
  password resets, receipts, platform alerts, run failures, digests. Every
  Opscend product sends through it — OpFlow, OpVault, OpSite, Reports — so it
  names the EVENT, not the product. One-line masthead, a first-class block for
  a one-time code, tables styled for alerts. No marketing chrome at all.

ROUTING RULE. The alias decides, and the alias is decided by the content:
  · Did Marcel write it himself, as himself? → MARCEL.
  · Is a human the author, but the company is the sender — onboarding, a reply
    from whoever is on duty, an announcement? → HELLO.
  · Is it a client's scheduled reporting? → REPORTS.
  · Did a system emit it? → NO-REPLY.
  If a no-reply send would carry a promotion, it is commercial email and it
  belongs in HELLO instead. The transactional exemption is real but narrow.

## 2 · Normalize the body BEFORE putting it in the shell

  1. IF THE BODY ALREADY CONTAINS A BLOCK TAG — <p>, <div>, <table>, <h1>–<h6>,
     <ul>, <ol>, <li>, <blockquote>, <pre>, <figure> — it is real HTML. Do not
     wrap it, do not escape it, do not second-guess it.

  2. IN THAT HTML, CONVERT A NEWLINE THAT SITS BETWEEN TEXT into <br>. Copy
     written as

       <p>Best,\nMarcel\nOpscend</p>

     is three lines to whoever wrote it and one line to HTML. Convert only a
     newline with text on its left; leave newlines between tags alone so you do
     not alter structure.

  3. OTHERWISE IT IS PLAIN TEXT. Escape & < > , split on blank lines into
     paragraphs, turn remaining single newlines into <br>, wrap each paragraph
     in <p>…</p>. Skipping this sends one run-on paragraph.

## 3 · Fill the shell

REPORTS
  {{preheader}}    one line, ~90 chars. The grey text after the subject in the
                   inbox list. Empty, and the client scrapes the first words of
                   the body instead, which is usually worse.
  {{client}}       REQUIRED. The client's name as they write it.
  {{period}}       REQUIRED. "August 2026", "Wk 35".
  {{{emailBody}}}  the normalized body. Triple brace — raw HTML, not escaped.
  {{reportUrl}}    the live report. Empty removes the button entirely.
  {{ctaLabel}}     the button's words. Default "View the live report".
  {{manageUrl}}    delivery preferences. Empty removes the line.

HELLO
  {{preheader}}
  {{{emailBody}}}     do NOT write your own sign-off into it — the shell sets
                      the signature, and two sign-offs is worse than one.
  {{signerName}}      REQUIRED. A person's name.
  {{signerTitle}}     REQUIRED. "Opscend" is enough if there is no title.
  {{postalAddress}}   REQUIRED. <br> between lines.
  {{unsubscribeUrl}}  REQUIRED. Must actually unsubscribe them.

MARCEL
  {{preheader}}
  {{{emailBody}}}     do NOT write a sign-off into it — the shell signs.
  {{purpose}}         REQUIRED, and it is NOT a slot in the markup — it is a
                      render-time control. Exactly one of:

                        correspondence   a reply, a thread, a client, anyone he
                                         already knows. NOT commercial email.
                                         No postal address, no opt-out — and an
                                         unsubscribe link on a reply is worse
                                         than useless, it tells a person they
                                         were on a list. Passing one THROWS.
                        outreach         a stranger, a first contact, or
                                         anything that promotes. THIS IS
                                         COMMERCIAL EMAIL. CAN-SPAM applies in
                                         full and both fields below become
                                         REQUIRED. Omitting them THROWS.

                      Do not reach for "correspondence" to get around a missing
                      address. The law follows who the recipient is, not which
                      string was easier to type.
  {{postalAddress}}   required when purpose is outreach. <br> between lines.
  {{unsubscribeUrl}}  required when purpose is outreach.

NO-REPLY
  {{preheader}}
  {{eventLabel}}   two or three words. "SIGN-IN CODE", "WORKFLOW FAILED",
                   "RECEIPT". Empty removes the line.
  {{code}}         a one-time code, set large in the mono. Empty removes the
                   block. NEVER put the code in the body as well — a code that
                   appears twice is a code someone mistypes.
  {{{emailBody}}}
  {{ctaUrl}}       the one action. Empty removes the button.
  {{ctaLabel}}     the button's words.

CONDITIONAL BLOCKS. A region wrapped in

    <!--#if ctaUrl--> … <!--#endif ctaUrl-->

is KEPT when that value is non-empty and REMOVED ENTIRELY when it is not. Email
has no logic; this is the substitute. Leave a marker in and you ship an HTML
comment; leave the block in with an empty href and you ship a dead button.

Replace EVERY occurrence of each token, not just the first.

The SUBJECT LINE is an email header, not markup. It is in none of these files.

## 4 · Check your work before sending

  · No "{{" survives anywhere.
  · No "<!--#if" or "<!--#endif" survives anywhere.
  · A HELLO email shows exactly ONE Unsubscribe anchor and a real postal
    address. Count the anchor TEXT — the href contains the word too.
  · A REPORTS or NO-REPLY email shows NO unsubscribe and no postal address.
  · A MARCEL email shows NO masthead — the copy is the first thing on the
    sheet. If you see a wordmark above the body you have filled the wrong file.
  · A MARCEL correspondence email shows no opt-out and no address. A MARCEL
    outreach email shows exactly one of each.
  · The body is inside the well. You have added no header, footer, logo or
    signature of your own — the frame is already built above and below it.

## 5 · What you must not change

  · ONE accent, #c9f227, AND IT IS A BLOCK FILL ONLY — the rule tick and the
    button ground. Acid type on paper fails contrast at every size. Never set
    type in it, never introduce a second accent.
  · Links are ink (#15170f) plus an underline, not a colour. That is the
    editorial read, not an oversight.
  · No capsule or pill tags. No blurred text, no glow text, no gradient blobs,
    no shadow-glows. Depth is a hairline or it is nothing.
  · The wordmark is LIVE TEXT, never an image. An image wordmark disappears
    when a client blocks images, and the header must survive that.
  · Do not edit a shell to suit one email. If a send needs something the shell
    cannot express, say so rather than modifying the frame.

## 6 · Known state — 2026-08-31

  · NOTHING HAS SENT. These shells are awaiting approval and are published to
    a preview host only.
  · NO POSTAL ADDRESS EXISTS for Opscend. hello@ cannot legally send until one
    does; the renderer enforces this rather than shipping a hole where the law
    goes.
  · NO OPT-OUT PAGE EXISTS for Opscend. Same blocker — and it also blocks
    marcel@ outreach, which needs the same pair. marcel@ CORRESPONDENCE is
    unaffected and can send today.
  · opscend.net IS THE ONLY DOMAIN OPSCEND OWNS. There is no opscend.com — it
    was assumed in an early draft of the sending Worker and never existed. Do
    not write it into an address, a link or a fallback.
  · marcel@opscend.net SENDS TODAY, through OpFlow's gmail.send_email on the
    "opscend gmail" connection (_connection_suffix "", is_html true, the
    rendered shell as the body). Marcel's standing rule: when he says send, you
    send — you do not draft.
  · reports@, hello@ and no-reply@ do NOT send yet. Gmail can only send from a
    configured Send-as alias, and the other path — the opscend-email Worker —
    is corrected to opscend.net in source but undeployed (the Cloudflare token
    has Pages, not Workers) with its domain not onboarded to Cloudflare Email
    Sending. For those three, compose and hand the file over.
  · Operating manual: Notion → "Opscend Email — How to Operate"
    https://app.notion.com/p/3ce4d6d2481081678e11c4e8bd8bbb4c
  · Canonical source is the private repo melockhart/opscend-email-shell →
    src/shells/. A published host is a copy. Never edit there.