@installagent/sdk 0.9.0 → 0.10.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (28) hide show
  1. package/dist/agent-mirror.d.ts +28 -0
  2. package/dist/agent-mirror.js +45 -20
  3. package/dist/client-drift.d.ts +120 -0
  4. package/dist/client-drift.js +556 -0
  5. package/dist/index.d.ts +3 -2
  6. package/dist/index.js +3 -2
  7. package/dist/linear-project.d.ts +18 -0
  8. package/dist/linear-project.js +43 -0
  9. package/dist/template-sync.d.ts +14 -0
  10. package/dist/template-sync.js +27 -0
  11. package/package.json +1 -1
  12. package/templates/workspace-root/AGENT.md +2 -0
  13. package/templates/workspace-root/AGENTS.md +10 -8
  14. package/templates/workspace-root/GEMINI.md +9 -21
  15. package/templates/workspace-root/ONBOARDING.md +3 -1
  16. package/templates/workspace-root/skills/CLAUDE.md +2 -2
  17. package/templates/workspace-root/skills/README.md +12 -4
  18. package/templates/workspace-root/skills/client-facing-docs/SKILL.md +3 -0
  19. package/templates/workspace-root/skills/client-latest/SKILL.md +75 -63
  20. package/templates/workspace-root/skills/engagement-spec/SKILL.md +14 -0
  21. package/templates/workspace-root/skills/engagement-spec/references/spec-templates.md +4 -0
  22. package/templates/workspace-root/skills/house-voice/SKILL.md +172 -77
  23. package/templates/workspace-root/skills/ia-cli/SKILL.md +2 -1
  24. package/templates/workspace-root/skills/installagent-brand-kit/SKILL.md +8 -0
  25. package/templates/workspace-root/skills/installagent-brand-kit/references/branded-pdf.md +8 -1
  26. package/templates/workspace-root/skills/installagent-brand-kit/scripts/brand.py +32 -5
  27. package/templates/workspace-root/skills/slack-voice/SKILL.md +2 -2
  28. package/templates/workspace-root/skills/tech-call-prep/SKILL.md +7 -2
@@ -3,19 +3,18 @@ name: house-voice
3
3
  description: >-
4
4
  Install Agent's house voice for anything a client reads: proposals, emails,
5
5
  onboarding guides, web and ad copy, client Slack replies. Patterns come
6
- verbatim from installagent.com: "you/your" address, plain
7
- concrete words, confident on value but hedged on numbers,
8
- name-the-objection-then-contrast, signature phrases to reuse. Sets the
9
- LENGTH BUDGET for every client message (Slack or email): highlights only,
10
- ~150 words for an update, max 6 bullets per list, one question, method in a
11
- thread reply or linked doc. Its SLACK section (the account owner's real
12
- client messages: greeting/bullets/ask/enthusiasm, hyphens not em dashes,
13
- emoji as status markers) wins over the marketing register for a client
14
- Slack reply. Use WHENEVER writing or reviewing client-facing sentences, or
15
- someone says "in our voice", "does this read on-brand", "tighten this
16
- copy", "too jargon-y", "too long", "cut the fluff", "highlights only".
17
- Governs WORDS; installagent-brand-kit governs visual brand; design-system
18
- governs screens.
6
+ from installagent.com: "you/your" address, plain concrete words, confident
7
+ on value but hedged on numbers, name-the-objection-then-contrast. For any
8
+ client message (Slack or email) it sets SHORT BY DEFAULT: answer first,
9
+ bullets for what changed, one ask last, detail in a thread, video, or doc.
10
+ No hard word cap, but past ~150 words stop and cut or split. Its SLACK
11
+ section (warm, light formatting, hyphens not em dashes, emoji as status
12
+ markers, personality in word choice, filler closers retired) wins over the
13
+ marketing register for a client Slack reply. Use WHENEVER writing or
14
+ reviewing client-facing sentences, or someone says "in our voice", "does
15
+ this read on-brand", "tighten this copy", "too jargon-y", "too long", "cut
16
+ the fluff", "highlights only". Governs WORDS; installagent-brand-kit
17
+ governs visual brand; design-system governs screens.
19
18
  ---
20
19
 
21
20
  # House voice
@@ -107,22 +106,32 @@ references to an AI system itself.)
107
106
  automation builds." A number or a named institution always beats an
108
107
  adjective like "world-class" used alone.
109
108
 
110
- ## Highlights only — the length budget
109
+ ## Short by default — client messages
111
110
 
112
111
  Clients read highlights, not the method. A long message is not more
113
112
  thorough: the client skims it, misses the ask, and replies late. This applies
114
113
  to client Slack and client email alike.
115
114
 
116
- **The budget for a client update:**
115
+ **The rule: say it short, keep the personality.** There is no hard word cap.
116
+ Default to a few lines.
117
117
 
118
- - **~150 words.** Count them before you send. Over budget means detail is
119
- still in the message.
118
+ - **Asks, answers, scheduling, bad news:** usually 60 words or fewer.
119
+ - **Updates:** as short as the news allows. Most fit in about 100 words.
120
+ - **150 words is a flag, not a wall.** Past it, stop and ask: can this be two
121
+ messages, a thread reply, a video, or a linked doc? Stay long only when the
122
+ client asked for the detail, or when it is a recap they will correct line
123
+ by line.
120
124
  - **Max 6 bullets per list**, one fact each. Most updates need two lists or
121
125
  fewer.
122
- - **One question**, on the last line before the close. Two only when both
123
- block the work.
126
+ - **One ask, last.** Two only when both block the work, and then number them.
124
127
  - **No item twice.** If a new feature is also a default, say it once.
125
128
 
129
+ **Why 150 is the flag.** Audit of 415 staff messages in 13 client channels,
130
+ Aug to Nov 2026: at 150 words or fewer the median client reply came in about
131
+ an hour and 45% of asks were answered in the first reply. Above 150 the median
132
+ reply took about 14 hours and 31% of asks were answered. The pattern held for
133
+ every writer. Length was the issue, not tone.
134
+
126
135
  **What stays:** what changed for them (the outcome, not how it works), the
127
136
  one number that matters, any default or decision they must confirm, the ask,
128
137
  the next step.
@@ -141,6 +150,12 @@ The cut test, line by line: **would the client miss it?** If not, delete it.
141
150
  When the client may want the method, send the highlights as the message and
142
151
  the method as a thread reply — or keep it ready and send it when they ask.
143
152
 
153
+ **Short is not curt.** The personality lives in word choice, one warm line,
154
+ an emoji used as a status marker, and light humor that matches the client. It
155
+ does not live in extra sentences. One warm beat per message is enough. Give
156
+ warmth more room in a welcome message, a real win (praise tied to a number),
157
+ or a finished milestone.
158
+
144
159
  **Before and after** — a real client update, 2026-10-08 (figures removed):
145
160
 
146
161
  | | Before | After |
@@ -152,14 +167,14 @@ the method as a thread reply — or keep it ready and send it when they ask.
152
167
  | Method | 7-step "how we count it" list | thread reply, only if asked |
153
168
  | Questions | 2, one buried mid-message | 1, on the last line |
154
169
 
155
- ## Slack, specifically — how the account owner actually writes
170
+ ## Slack, specifically — how we write to clients
156
171
 
157
172
  The landing page is the *marketing* register. Day-to-day client Slack is a
158
- different, warmer register, and it has its own consistent shape. Pulled from
159
- Angello's real messages across `#client-jared-tomseth`,
160
- `#client-behaviatherapy-team`, `#client-carvision` and `#client-iloveanthonys`,
161
- July 2026. When drafting a Slack message for a client, match **this** section
162
- first and the landing-page pillars second.
173
+ different, warmer register with its own shape. It started from the account
174
+ owner's client messages (July 2026). It was re-checked on 2026-11-04 against
175
+ 90 days of messages from five writers across 13 client channels. When drafting
176
+ a Slack message for a client, match **this** section first and the landing-page
177
+ pillars second.
163
178
 
164
179
  > **Client only.** This register is for a message a client reads. For an
165
180
  > internal message — a teammate DM, `#team-techs`, a status post — use
@@ -167,55 +182,129 @@ first and the landing-page pillars second.
167
182
  > number. Applying this section internally is what produced the DM that got
168
183
  > "Bro, can we please use english" on 2026-08-11.
169
184
 
170
- **The reliable skeleton of a substantive message:**
185
+ **The order of a substantive message:**
171
186
 
172
- 1. Warm one-line greeting with the person's @name
173
- 2. One line of gratitude or momentum — *"thank you for taking the time"*,
174
- *"Really enjoyed the call today"*, *"thank you for sending everything over
175
- quickly"*
176
- 3. The substance, as **bullets** (`•`, sub-bullets `◦`) or a numbered list —
177
- never long paragraphs, highlights only, inside the
178
- [length budget](#highlights-only--the-length-budget)
179
- 4. One explicit, short ask — when there truly are two, he heads them
180
- *"Two questions for you:"*
181
- 5. Close on next step + genuine enthusiasm — *"Excited to get going on this"*
187
+ 1. **Short greeting with the name.** One line. Skip it in a fast back-and-forth.
188
+ 2. **The answer, the number, or the news — first.** Not the background.
189
+ 3. **Bullets for what changed** (`•`, sub-bullets `◦`) or a numbered list.
190
+ Outcome, not method.
191
+ 4. **One ask, last line.** A yes or no question, or two named options. When
192
+ there are two that block the work, number them: *"Need from you: 1, 2"*.
193
+ 5. **Next step with a date, or nothing.** A short warm close is fine. A closer
194
+ line is not required.
195
+
196
+ **Live back-and-forth is a different mode.** When the client is online and
197
+ replying, drop the greeting and the sign-off. Answer in one or two lines. The
198
+ fastest replies in the audit (1 to 6 minutes) mostly came to messages of 15 to
199
+ 60 words like this.
182
200
 
183
201
  **Openers actually used:** "Morning [name] -", "Good morning!", "Hi [name]!!",
184
202
  "Hey [name]!", "Heyo", "Gm!", "Thanks for taking the time to speak today".
185
203
 
186
- **Signature phrases — reuse verbatim:**
187
-
188
- - "let me know if you have any questions" / "As always, let me know if any
189
- questions or concerns"
190
- - "please don't hesitate to reach out"
191
- - "I'll reach out if I find I missed anything"
192
- - "thank you for taking the time"
193
- - "Excited to get going on this" / "excited to start tackling all this"
194
- - "With that said, ..." · "Regarding [X], ..." · "As for [X], ..." · "Lastly, ..."
195
- - "worth noting ..."
196
- - "I prefer giving conservative timelines so I estimate [date]"
197
-
198
- **Mechanics that make it sound like him and not like a bot:**
199
-
200
- - **Hyphens, not em dashes.** He writes " - " where a writer would use "—".
201
- This is the single most recognisable tell. Do not "upgrade" his dashes.
202
- - **Emoji, used as punctuation and as status markers.** 🫡 is his most frequent
203
- sign-off beat; also 🙂 🙏 🎉 ⚡ 👀. In update lists he uses ✅ (done), ✍️ (in
204
- progress), 🏁 (queued), 🟡 (deferred) as row markers.
205
- - **"We" for the company's work, "I" for his own actions.** "We'll get to work"
204
+ **Phrases: keep, use sparingly, retire.**
205
+
206
+ - **Keep as flavor** (once per conversation, not on every message):
207
+ "thank you for taking the time" · "Really enjoyed the call today" · "I'll
208
+ reach out if I find I missed anything" · "worth noting ..." · "With that
209
+ said, ..." · "Regarding [X], ..." · "Lastly, ..." · "I prefer giving
210
+ conservative timelines so I estimate [date]".
211
+ - **Use sparingly.** "Excited to get going on this" — welcome and kickoff
212
+ messages only. "Let me know if you have any questions" — only when the message
213
+ has no ask and the client may truly want to follow up. Never on a message over
214
+ about 100 words, and never next to an ask. It makes the ask look optional.
215
+ - **Retire.** "As always, let me know if any questions or concerns" (the most
216
+ common filler in the audit) · "please don't hesitate to reach out" · "Hope
217
+ your week is going great" · "quick update" or "quick heads-up" on anything
218
+ longer than three lines · "sorry for the long message" (cut the message
219
+ instead) · tool footers such as "Sent using Claude".
220
+
221
+ **Moves that get answers:**
222
+
223
+ - **One purpose per message.** Send the ask alone, not inside an update.
224
+ - **Bad news in the first line.** The number, the cause, a safe default, a date.
225
+ Around 60 words. Example: *"The test came in at 70%. Our bar is 90%. Cause:
226
+ [one line]. Keep yours running as it is. New result Thursday."*
227
+ - **Click steps go in a second message.** A numbered list of 6 steps or fewer.
228
+ Put the method in a video, a doc, or a thread. Do not paste the steps and also
229
+ link a video that covers them.
230
+ - **State a guess as a guess.** "I can't prove this, but I think X." The client
231
+ corrects it in minutes.
232
+ - **Defaults lower the work.** "If I hear nothing by Thursday, I'll assume X."
233
+ "Nothing you need to change."
234
+ - **Recaps the client can fix.** Group by topic. End with one list called "from
235
+ you". Keep it short.
236
+ - **Go-live note says where to look.** Where the client sees the result, and in
237
+ which app.
238
+ - **Praise tied to a number.** "Your push moved this from X to Y." Praise alone
239
+ does not land.
240
+ - **Own a miss in one line.** "We should have asked a clearer question."
241
+ - **Give a time and meet it.** "Tomorrow at 7."
242
+ - **Name the thing.** Never "the above" or a bare link. Say what the link is
243
+ and what to do with it.
244
+
245
+ **Match the room:**
246
+
247
+ - **Match the channel.** If a client says "use email", use email. One email-first
248
+ client left 58% of Slack messages without a reply.
249
+ - **Match the tone.** Warm and casual with a warm client. With a short or
250
+ irritated client, drop the hype words and the emoji, and get to the point.
251
+
252
+ **Mechanics that make it sound like us and not like a bot:**
253
+
254
+ - **Hyphens, not em dashes.** Write " - " where a writer would use "—". This is
255
+ the single most recognisable tell. Do not "upgrade" the dashes.
256
+ - **Emoji, used as punctuation and as status markers.** 🫡 is the most frequent
257
+ sign-off beat; also 🙂 🙏 🎉 ⚡ 👀. In update lists use ✅ (done), ✍️ (in
258
+ progress), 🏁 (queued), 🟡 (deferred) as row markers. One to three per message.
259
+ - **"We" for the company's work, "I" for your own actions.** "We'll get to work"
206
260
  but "I'll send over everything we spoke about tonight."
207
261
  - **Light informality is on-voice**, including the occasional lowercase start
208
262
  and clipped line ("awesome, thank you -"). Don't over-polish it into
209
263
  corporate register.
210
- - **Conservative on dates, by explicit policy.** He says he prefers
211
- conservative timelines and then names one — this is the Slack form of the
212
- landing page's hedging pillar.
213
- - **Asks for an explicit ack** when something matters: *"Give me a ✅ once
214
- you've read the message"*.
215
-
216
- **What he does not do:** long unbroken paragraphs, headers inside a Slack
217
- message, bold-heavy formatting, hedging apologies, or hype adjectives. Bad
218
- news is delivered plainly and immediately, then followed by the plan.
264
+ - **Conservative on dates, by explicit policy.** Say you prefer conservative
265
+ timelines, then name one. This is the Slack form of the hedging pillar.
266
+ - **Ask for an explicit ack** only when something matters: *"Give me a ✅ once
267
+ you've read the message"*. Do not use an emoji as the only way to answer. One
268
+ client could not find where to give the thumbs up.
269
+ - **One thought, one message.** No bursts of three to five posts. Fix a typo by
270
+ editing the message, not by posting a correction line.
271
+ - **Plain symbols only.** No arrows like "-->". They read like code.
272
+
273
+ **Never in a client channel:**
274
+
275
+ - Passwords, logins, or one-time codes. Send them through the team's secure
276
+ intake path. If a client posts one, tell them gently and move to that path.
277
+ - Another client's name or details.
278
+ - Staff-to-staff talk, jokes about a failed demo, or "this will break" remarks.
279
+ The client can read all of it.
280
+ - A promise to work around something the client asked for.
281
+
282
+ **Slack examples** (generic, no client content):
283
+
284
+ Welcome (warmth gets room here):
285
+
286
+ > Hey [name]! Really enjoyed the call today 🙂
287
+ > Here's what happens next:
288
+ > • I set up your [system] this week
289
+ > • First results land by [date]
290
+ > • Nothing needed from you yet
291
+ >
292
+ > Excited to get going on this.
293
+
294
+ Update:
295
+
296
+ > Morning [name] - the inbox sort is live ✅
297
+ > • [N] emails sorted since Monday, [N] needed a manual fix
298
+ > • Newsletters now skip your inbox
299
+ > • Nothing you need to change
300
+ >
301
+ > One question: should invoices get their own folder?
302
+
303
+ **What we do not do:** long unbroken paragraphs, headers inside a Slack
304
+ message, bold-heavy formatting (one bold label for the ask is fine), hedging
305
+ apologies, hype adjectives, or a stack of greeting plus thanks plus closer
306
+ around a short message. Bad news is delivered plainly and immediately, then
307
+ followed by the plan.
219
308
 
220
309
  ## Quick before/after
221
310
 
@@ -249,23 +338,29 @@ news is delivered plainly and immediately, then followed by the plan.
249
338
  three vague ones.
250
339
  - **Second person throughout** in anything a client reads.
251
340
  - **Reuse the signature phrases verbatim** rather than drafting
252
- near-equivalents — consistency across every artifact is the point.
341
+ near-equivalents — consistency across every artifact is the point. *(Applies
342
+ to the marketing register. For client Slack, use the keep / sparingly /
343
+ retire list above.)*
253
344
 
254
345
  ## Before you finish — checklist
255
346
 
256
347
  - [ ] Reads like a person talking to the reader, not a deck abstract.
257
- - [ ] **If it's a client message (Slack or email)**: words counted, ~150 or
258
- fewer for an update; max 6 bullets per list; one question; nothing
259
- said twice; the method moved to a thread reply or a linked doc.
348
+ - [ ] **If it's a client message (Slack or email)**: short by default. Answer
349
+ or number first. Max 6 bullets per list. One ask, last. Nothing said
350
+ twice. Method moved to a thread reply, a video, or a linked doc. Over
351
+ ~150 words only with a reason.
260
352
  - [ ] No banned hype word from the table above.
261
353
  - [ ] At least one claim is backed by a concrete number, name, or example.
262
354
  - [ ] Any bold number/timeline claim is hedged the way the source hedges
263
355
  ("most," "typically," a range) rather than promised outright.
264
356
  - [ ] Signature phrases ("at a fraction of the cost of a full-time hire")
265
357
  reused verbatim, not paraphrased.
266
- - [ ] **If it's a client Slack message**: greeting → bullets → explicit ask →
267
- next step + enthusiasm; hyphens not em dashes; no headers or heavy bold;
268
- at least one of his signature closers.
358
+ - [ ] **If it's a client Slack message**: greeting with the name (or none, in a
359
+ fast reply) → answer first → bullets → one ask last; hyphens not em
360
+ dashes; no headers or heavy bold; no retired closer; one warm beat of
361
+ personality.
362
+ - [ ] **If it's a client Slack message**: no password or code, no other client's
363
+ name, no staff-to-staff chat.
269
364
  - [ ] If this is going somewhere permanent, spot-check
270
365
  `references/source-copy.md` (or the live page) hasn't drifted.
271
366
 
@@ -275,8 +370,8 @@ The landing page is the source of truth for the marketing register, not this
275
370
  skill. If `installagent.com/get-started` copy changes materially, re-pull it
276
371
  into `references/source-copy.md` and update the patterns above in the same pass.
277
372
 
278
- The **Slack section** has a different source of truth: the account owner's own
279
- messages in the live `#client-*` channels. It was last pulled 2026-07-31. If his
280
- writing drifts — or if someone else starts owning client channels — re-sample a
281
- few recent substantive messages per channel and update that section rather than
282
- letting the two diverge silently.
373
+ The **Slack section** has a different source of truth: staff messages in the
374
+ live `#client-*` channels. It was last re-checked 2026-11-04 (90 days, five
375
+ writers, 13 channels). Re-sample about every 60 days. Check the reply-time and
376
+ ask-answered numbers in "Short by default" at the same time. Update that
377
+ section rather than letting the two diverge silently.
@@ -6,7 +6,7 @@ description: >-
6
6
  doctor`. Use this WHENEVER a task matches an existing `ia` operation:
7
7
  "what's the status / context on client [slug]?" (do not grep repos or
8
8
  hand-draft API calls; `ia client`, `ia client-build`, `ia client-drive`, `ia
9
- client-linear` do it read-only), starting a new client engagement, building
9
+ client-linear`, `ia client-drift` do it read-only), starting a new client engagement, building
10
10
  an n8n automation (check the bank first), running an email-triage gate
11
11
  ("write the soak report", "sample for gate B", "is the triage agent still
12
12
  recording?"; `ia triage` writes the evidence file from the classification
@@ -41,6 +41,7 @@ secrets).
41
41
  | What's in client X's build repo docs? | `ia client-build <slug> [query]` |
42
42
  | Find a client's call transcript / Drive deliverable | `ia client-drive <slug> [query]` |
43
43
  | Open Linear issues for a client | `ia client-linear <slug> [query]` |
44
+ | Did anything drift? / does client X's repo still agree with n8n, Linear and git? | `ia client-drift <slug> [--json]` (`--all` for every client repo) — read-only: Builds vs n8n (active flag, missing workflow, SHADOW/TEST names), exports vs the instance, silent schedules and failed last runs (status only), git and open PRs, Linear vs the delivery log, the repo's drift lint (rules 12–19). Exit 1 on drift or when a source could not be read. The `client-latest` skill runs it for you |
44
45
  | Open issues in an internal Linear project | `ia linear-project <project> [query]` |
45
46
  | Start a new client engagement | `ia client-intake <slug> --name <name>` (or bare `ia new-client <slug>`) |
46
47
  | Client repos drifted from client-template's lint/CI files | `ia template-sync [--apply]` |
@@ -80,6 +80,12 @@ numbers. Then `brand.render_pdf(body, out)` rasterizes via WeasyPrint. Content
80
80
  discipline stays with `engagement-spec` (overviews/onboarding) and
81
81
  `contract-tech-agnostic` (SOWs) — this skill only guarantees the brand.
82
82
 
83
+ **No dates in a generated PDF.** `render_pdf` raises `ValueError` if the visible
84
+ text holds a calendar date (cover date, "as of", ISO stamp). A dated PDF is
85
+ stale the day after it ships. Pass `allow_dates=True` only when the user
86
+ explicitly asks for a date (for example a dated timeline or an effective date).
87
+ Blank signature date lines are fine.
88
+
83
89
  ### Client deck (Google Slides)
84
90
 
85
91
  Two paths, one gate — full detail in
@@ -143,6 +149,8 @@ images. The logo assets here are copies of
143
149
  other hue.
144
150
  - [ ] Official logo used (PDF hero + running header); no generic glyph.
145
151
  - [ ] Generator imports `scripts/brand.py` — no hard-coded hexes.
152
+ - [ ] PDF has no dates (`render_pdf` enforces it); `allow_dates=True` only on
153
+ an explicit ask.
146
154
  - [ ] Excalidraw validates / opens; PDF previewed as PNG.
147
155
  - [ ] Deck: `deck_lint.py --render` clean **and every slide looked at** — a
148
156
  clean geometry pass is not a clean deck.
@@ -15,12 +15,17 @@ body = brand.pdf_hero(
15
15
  kicker="Statement of Work & Proposal",
16
16
  title="CarVision Pricing Agent — Phase 1",
17
17
  sub="A daily used-car repricing co-pilot.",
18
- meta_html='<div class="kicker" style="color:#8a93a0">June 16, 2026 · Confidential</div>',
18
+ meta_html='<div class="kicker" style="color:#8a93a0">Confidential</div>',
19
19
  )
20
20
  body += "<h2><span class='n'>1</span>Summary</h2><p>…</p>" # your content
21
21
  brand.render_pdf(body, "client-<slug>/.../Proposal.pdf")
22
22
  ```
23
23
 
24
+ **No dates.** `render_pdf()` scans the visible text and raises `ValueError` on
25
+ any calendar date (`June 16, 2026`, `16 June 2026`, `October 2026`,
26
+ `2026-10-20`, `10/20/26`). Do not date the cover, the footer, or an "as of"
27
+ line. Pass `allow_dates=True` only when the user explicitly asks for a date.
28
+
24
29
  - `pdf_hero()` emits the **official logo** (full lockup in the hero, icon-only in
25
30
  the running header) — no generic mark. The wordmark is set to ink on white.
26
31
  - `pdf_css()` provides page setup (Letter, margins), a running footer with
@@ -62,5 +67,7 @@ brand.render_pdf(body, "client-<slug>/.../Proposal.pdf")
62
67
  - Client-facing wording follows **contract-tech-agnostic** (SOWs) and
63
68
  **engagement-spec** (overviews/onboarding) — this skill governs *brand*, those
64
69
  govern *content*.
70
+ - **No dates in a generated PDF** unless the user explicitly asks
71
+ (`allow_dates=True`). Undated copy never goes stale.
65
72
  - Flag placeholders (`[legal entity]`, `[signatory]`) so they're filled before
66
73
  sending.
@@ -12,7 +12,7 @@ Light surfaces (client PDFs + diagrams on white) use the ink/muted neutrals
12
12
  below; the dark marketing-site neutrals in theme.css are NOT for documents.
13
13
  """
14
14
  from __future__ import annotations
15
- import json, math, random
15
+ import html, json, math, random, re
16
16
  from pathlib import Path
17
17
 
18
18
  # ─── Brand palette (mirror of theme.css — Design System v1.0 Signal Red) ─────
@@ -167,9 +167,36 @@ def pdf_hero(kicker, title, sub, meta_html="") -> str:
167
167
  {meta_html}
168
168
  </div>"""
169
169
 
170
- def render_pdf(html_body: str, out_path: str, head_extra: str = ""):
171
- """Render an HTML body (after pdf_hero + content) to a branded PDF."""
170
+ _MONTH = (r"(?:Jan(?:uary)?|Feb(?:ruary)?|Mar(?:ch)?|Apr(?:il)?|May|June?|July?|"
171
+ r"Aug(?:ust)?|Sep(?:t(?:ember)?)?|Oct(?:ober)?|Nov(?:ember)?|Dec(?:ember)?)")
172
+ _DATE_RES = [re.compile(p) for p in (
173
+ rf"\b{_MONTH}\.? \d{{1,2}}(?:st|nd|rd|th)?\b(?:,? \d{{4}})?", # June 16, 2026 / Oct 20
174
+ rf"\b\d{{1,2}}(?:st|nd|rd|th)? {_MONTH}\b\.?(?:,? \d{{4}})?", # 16 June 2026
175
+ rf"\b{_MONTH}\.?,? \d{{4}}\b", # October 2026
176
+ r"\b\d{4}-\d{2}-\d{2}\b", # 2026-10-20
177
+ r"\b\d{1,2}/\d{1,2}/\d{2,4}\b", # 10/20/26
178
+ )]
179
+
180
+ def find_dates(html_body: str) -> list[str]:
181
+ """Calendar dates in the VISIBLE text of an HTML body (tags, <style> and
182
+ <script> are ignored). Used by render_pdf to refuse dated PDFs."""
183
+ text = re.sub(r"(?is)<(style|script)\b.*?</\1>", " ", html_body)
184
+ text = re.sub(r"\s+", " ", html.unescape(re.sub(r"<[^>]+>", " ", text))) # \s covers &nbsp;
185
+ return [m.group(0) for rx in _DATE_RES for m in rx.finditer(text)]
186
+
187
+ def render_pdf(html_body: str, out_path: str, head_extra: str = "", allow_dates: bool = False):
188
+ """Render an HTML body (after pdf_hero + content) to a branded PDF.
189
+
190
+ House rule: a generated PDF carries NO dates (no cover date, no "as of",
191
+ no ISO stamps). A dated PDF goes stale the day after it is sent. Pass
192
+ allow_dates=True only when a date is explicitly requested (a signed
193
+ effective date, a dated timeline). Blank signature date lines are fine."""
194
+ found = find_dates(html_body)
195
+ if found and not allow_dates:
196
+ raise ValueError(
197
+ "PDF text contains date(s): " + ", ".join(sorted(set(found))[:8])
198
+ + ". Remove them, or pass allow_dates=True if the date was explicitly requested.")
172
199
  from weasyprint import HTML
173
- html = f"<!DOCTYPE html><html><head><meta charset='utf-8'><style>{pdf_css()}{head_extra}</style></head><body>{html_body}</body></html>"
174
- HTML(string=html, base_url=str(ASSET_DIR)).write_pdf(out_path)
200
+ html_doc =f"<!DOCTYPE html><html><head><meta charset='utf-8'><style>{pdf_css()}{head_extra}</style></head><body>{html_body}</body></html>"
201
+ HTML(string=html_doc, base_url=str(ASSET_DIR)).write_pdf(out_path)
175
202
  return out_path
@@ -11,13 +11,13 @@ description: >-
11
11
  because a ~400-word DM on 2026-08-11 got the reply "Bro, can we please use
12
12
  english". Length is not thoroughness in a message — it is a delivery
13
13
  failure. INTERNAL only. For a message a CLIENT reads, use house-voice: its
14
- length budget and Slack section win there. Does NOT apply to repo docs,
14
+ short-by-default rules and Slack section win there. Does NOT apply to repo docs,
15
15
  evidence/ files, commit bodies, PR descriptions, or Linear issues; those
16
16
  stay detailed.
17
17
  ---
18
18
 
19
19
  > **Which skill applies.** Internal teammate (Slack, email, chat) → this file.
20
- > Client → `house-voice` § *Highlights only* and § *Slack, specifically*. The
20
+ > Client → `house-voice` § *Short by default* and § *Slack, specifically*. The
21
21
  > registers are different on purpose: a client gets a greeting and an explicit
22
22
  > ask; Angello gets a link and a number.
23
23
 
@@ -113,12 +113,15 @@ first (`client-template`), not a call agenda.
113
113
  ### 3. Write `docs/05-call-agenda.md`
114
114
 
115
115
  One file in the build repo, overwritten per call (it's a prep artifact,
116
- not a record — records are registry call notes). If an old
116
+ not a record — records are registry call notes). The line under its title
117
+ is `Type: spec` (repo-lint rule 19, `AGENT.md` § docs/): it is true for the
118
+ next call and edited in place, never archived. If an old
117
119
  `05-call-sheet.md` exists from before the agenda format, this supersedes
118
120
  it — remove the old file in the same change. Structure:
119
121
 
120
122
  ```markdown
121
123
  # Call agenda — <Client> — <call type> — <YYYY-MM-DD>
124
+ Type: spec
122
125
 
123
126
  > Generated <date> by tech-call-prep. Script: team hub → Techs → Discovery call.
124
127
  > Logistics: designated recorder = <name> (ONE bot only) · red-dot check at
@@ -191,7 +194,8 @@ the technician can read it from any device mid-call). If the kickoff's
191
194
  auto-drafted Doc from step 1 exists, update **that Doc in place** rather
192
195
  than creating a second one — one agenda per call, everywhere. The Drive
193
196
  copy is for running the call; the build-repo file remains the versioned
194
- source.
197
+ source. Leave the `Type:` line out of the Drive copy — it is a repo
198
+ convention.
195
199
 
196
200
  ## Quality rules
197
201
 
@@ -231,4 +235,5 @@ source.
231
235
  - [ ] Vertical context comes from a real playbook file — or its absence
232
236
  is a prep-gap line, not a silently missing section.
233
237
  - [ ] Old `05-call-sheet.md` removed if it existed.
238
+ - [ ] `docs/05-call-agenda.md` has `Type: spec` on the line under its title.
234
239
  - [ ] Drive copy placed/updated at the root of the client's Drive folder.