Trainer: tell the words model who opens each mail

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01GT37Z1Xtfd9pUuQtMTg6Yt

CHANGELOG.md

@@ -4,6 +4,10 @@ One line per change, grouped by the release that shipped it. Newest
 first. A release is a Cargo.toml bump plus a `v<version>` tag; the
 content repos pin the tag they run (see the end of this file).
 
+## 0.6.12 (2026-10-01)
+
+- Trainer: the words model is told who opens each mail: the person who sent the case, the person who posted the record an answer is about, or someone at the business. Mails to the business about another person's case used to be written as if to that person ("you will hear from us"); on Gullberg, three of nine were.
+
 ## 0.6.11 (2026-10-01)
 
 - `wordmark_ink: true` in `site.yaml`: an SVG wordmark is drawn in the page's own ink, as a mask over the text colour, so it follows the page's light and dark in every browser. A wordmark shown as an `<img>` only knows the system's setting, and some browsers don't pass even that on. Opacity in the file still shows, so a lighter line stays lighter. Opt-in, for one-colour marks; a mark with a colour of its own keeps its colours.

Cargo.lock

@@ -3357,7 +3357,7 @@ dependencies = [
 
 [[package]]
 name = "portal"
-version = "0.6.10"
+version = "0.6.11"
 dependencies = [
  "anyhow",
  "arc-swap",

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "portal"
-version = "0.6.10"
+version = "0.6.11"
 edition = "2021"
 
 [lib]

src/trainer/build.rs

@@ -2524,6 +2524,8 @@ pub fn render(plan: &Plan, words: &BTreeMap<String, Value>) -> anyhow::Result<BT
     files.into_iter().map(|(path, value)| Ok((path, serde_yaml::to_string(&value)?))).collect()
 }
 
+const MAILS_PURPOSE: &str = "the mails the site sends. Under each bucket, each stage that sends one has a `subject` and a `body`: the mail a person gets the moment their case enters that stage, saying what happened and what, if anything, they can do now. Plain text, at most three short sentences plus the link line, no greeting longer than one word, in the business's voice. Keep every `{...}` placeholder exactly as it is - `{site}`, `{chain}`, `{email}` and any field name are filled in by the site - and keep any line with a link in it. The person reads the mail alone, days later, maybe among others, so what works is a mail that says what it is about in their terms - a field they filled in, as a `{placeholder}`, names their case far better than `this` or `your message` (each bucket's fields are listed under the needs above) - and ends with the business's name so they know who wrote. Short fields (a name, a place, a choice) make good subjects; a field marked `(long)` is a whole answer and a field marked `(optional)` may be blank, so those serve better elsewhere or not at all. A desk's decision carries no written reason, but a reply to the mail reaches the people who decided, so inviting a reply is the honest way to offer an explanation.";
+
 const DESK_PURPOSE: &str = "a desk: the page one role inside the business works from. Under `buckets`, each entry is a list of cases; `moves` are the buttons that move a case from one stage to the next (key `from->to`), so label each with what the person has just done. Under `links` are pages this role can open. Under `invites`, each entry is a form that invites a person into that group - they get an account and a one-time link - and `invited` is the list of invites sent, where `again` is the button that sends an invite whose link ran out once more. `suggestions`, on the desk that has it, is the list of changes the people responsible for a page have suggested: `looking`, `changed` and `declined` are its buttons.";
 
 /// The page about who the business is: a question with nothing to do
@@ -2634,13 +2636,35 @@ fn words_prompt(plan: &Plan, path: &str, fallback: &Value, tone: Option<&str>) -
         Some(n) => format!("a page shown right after someone in the group `{}` has sent a form from inside the business. The reader is that colleague, at work, not a visitor: nobody comes back to them. Say what has now happened to what they entered, and who it reaches.", n.enters_as.as_deref().unwrap_or_default()),
         None => "a page shown right after someone has sent a form. Say who reads it, when they answer, and what happens next.".to_string(),
     };
+    // Who reads each mail. A mail to the business about someone else's
+    // case was written as if to the person who sent it ("you will hear
+    // from us") until the model was told who opens it.
+    let recipients: Vec<String> = plan
+        .needs
+        .iter()
+        .flat_map(|n| {
+            n.mails.iter().map(move |(stage, to)| {
+                let reader = match to.as_str() {
+                    "submitter" => "the person who sent it".to_string(),
+                    "owner" => "the person who posted the record this answers".to_string(),
+                    address => format!("someone at the business ({address}), about another person's case; write to them, not to the person who sent it"),
+                };
+                format!("- `{}` entering `{stage}`: read by {reader}", n.lands_in)
+            })
+        })
+        .collect();
+    let mails_purpose = format!(
+        "{MAILS_PURPOSE}\n\nWho opens each mail:\n{}",
+        recipients.join("\n")
+    );
     let who_purpose = "the page about who the business is, with nothing to do on it, only things to read. `question` asks it as a question (\"Who are we?\"). Under `presents`, each entry heads one list shown as cards with a picture each - the people who work there, the work they have done - loosely, as a person would introduce them. `values` heads the business's own statements, which are its facts: head them, never add to them.".to_string();
     let purpose = if path == who_page_path(plan) {
         who_purpose.as_str()
     } else if path == "site.yaml" {
         "the invite mail: the first mail a person gets when a member of the business brings them in to help (onto a desk, into a committee), carrying the one-time link that lets them set a password. `subject` and `body` under `invite`. They did not ask for it, so say who brought them in and to what, then the link and when it runs out, then where they sign in afterwards. Plain text, short lines. Keep every `{...}` placeholder exactly as it is: `{name}`, `{username}`, `{group}`, `{link}`, `{expires}`, `{site}`, `{site_name}` are filled in by the site, and `{link}` must stay on a line of its own."
     } else if path == "aggregates.yaml" {
-        "the mails the site sends. Under each bucket, each stage that sends one has a `subject` and a `body`: the mail a person gets the moment their case enters that stage, saying what happened and what, if anything, they can do now. Plain text, at most three short sentences plus the link line, no greeting longer than one word, in the business's voice. Keep every `{...}` placeholder exactly as it is - `{site}`, `{chain}`, `{email}` and any field name are filled in by the site - and keep any line with a link in it. The person reads the mail alone, days later, maybe among others, so what works is a mail that says what it is about in their terms - a field they filled in, as a `{placeholder}`, names their case far better than `this` or `your message` (each bucket's fields are listed under the needs above) - and ends with the business's name so they know who wrote. Short fields (a name, a place, a choice) make good subjects; a field marked `(long)` is a whole answer and a field marked `(optional)` may be blank, so those serve better elsewhere or not at all. A desk's decision carries no written reason, but a reply to the mail reaches the people who decided, so inviting a reply is the honest way to offer an explanation."
+        mails_purpose.as_str()
+
     } else if path.contains("/decide/") {
         "a page the person who sent a form reaches later, through a private link, to make a decision that is theirs: under `moves`, each entry is one thing they can decide."
     } else if path == "questions/index.yaml" {
@@ -3223,6 +3247,14 @@ mod tests {
         assert!(bad.validate().unwrap_err().to_string().contains("multiple is for select"));
     }
 
+    #[test]
+    fn the_words_model_is_told_who_opens_each_mail() {
+        let plan: Plan = serde_yaml::from_str("business: Vel\ncontact: { name: S, email: s@v.example }\nmail: { from: v@v.example }\nneeds:\n  - id: notice\n    who: en nabo\n    wants: et oppslag\n    lands_in: oppslag\n    handled_by: redaktor\n    stages: [open, tatt_ned]\n    done_when: [tatt_ned]\n    mails: { open: s@v.example }\n    watched_by: [public]\n    max_fields: 2\n    collects:\n      - { name: email, type: email }\n  - id: answer\n    who: en nabo\n    wants: svare\n    about: notice\n    lands_in: svar\n    handled_by: redaktor\n    stages: [open, lest]\n    done_when: [lest]\n    mails: { open: owner }\n    max_fields: 1\n    collects:\n      - { name: email, type: email }\n").unwrap();
+        let prompt = words_prompt(&plan, "aggregates.yaml", &json!({}), None);
+        assert!(prompt.contains("`oppslag` entering `open`: read by someone at the business (s@v.example)"), "{prompt}");
+        assert!(prompt.contains("`svar` entering `open`: read by the person who posted the record this answers"));
+    }
+
     #[test]
     fn a_need_no_persona_tries_is_named() {
         let plan: Plan = serde_yaml::from_str("business: B\ncontact: { name: I, email: i@b.example }\nmail: { from: post@b.example }\nneeds:\n  - id: ask\n    who: a customer\n    wants: an answer\n    lands_in: asks\n    handled_by: desk\n    stages: [open, done]\n    done_when: [done]\n    max_fields: 2\n    collects:\n      - { name: email, type: email }\n  - id: card\n    who: one of us\n    wants: to be seen\n    enters_as: desk\n    lands_in: cards\n    handled_by: desk\n    stages: [open, gone]\n    done_when: [gone]\n    max_fields: 1\n    collects:\n      - { name: name }\n  - id: later\n    who: someone\n    wants: something\n    paused: true\n    lands_in: later\n    handled_by: desk\n    stages: [open, done]\n    done_when: [done]\n    max_fields: 1\n    collects:\n      - { name: email, type: email }\npersonas:\n  - { id: p, need: ask, text: I need an answer }\n").unwrap();