@installagent/sdk 0.1.0 → 0.2.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 (80) hide show
  1. package/dist/agent-templates.d.ts +36 -2
  2. package/dist/agent-templates.js +173 -3
  3. package/dist/client-linear-create.d.ts +26 -0
  4. package/dist/client-linear-create.js +46 -0
  5. package/dist/client-linear.d.ts +28 -9
  6. package/dist/client-linear.js +36 -14
  7. package/dist/docs-search.d.ts +19 -6
  8. package/dist/docs-search.js +32 -11
  9. package/dist/doctor.d.ts +9 -0
  10. package/dist/doctor.js +126 -23
  11. package/dist/env-fill.d.ts +13 -0
  12. package/dist/env-fill.js +34 -9
  13. package/dist/env-push.d.ts +3 -0
  14. package/dist/env-push.js +11 -6
  15. package/dist/env-registry.d.ts +25 -0
  16. package/dist/env-registry.js +69 -7
  17. package/dist/exec.js +15 -2
  18. package/dist/index.d.ts +14 -6
  19. package/dist/index.js +14 -6
  20. package/dist/linear-project.d.ts +2 -2
  21. package/dist/linear-project.js +2 -2
  22. package/dist/log.d.ts +28 -0
  23. package/dist/log.js +73 -0
  24. package/dist/n8n-executions.d.ts +85 -0
  25. package/dist/n8n-executions.js +259 -0
  26. package/dist/op-cli.d.ts +29 -0
  27. package/dist/op-cli.js +52 -0
  28. package/dist/platform.d.ts +35 -0
  29. package/dist/platform.js +39 -0
  30. package/dist/portal-admin.d.ts +40 -0
  31. package/dist/portal-admin.js +30 -0
  32. package/dist/standup.d.ts +88 -0
  33. package/dist/standup.js +235 -0
  34. package/dist/sync-repos.d.ts +47 -0
  35. package/dist/sync-repos.js +80 -0
  36. package/dist/template-sync.d.ts +10 -0
  37. package/dist/template-sync.js +11 -0
  38. package/dist/wizard.d.ts +15 -0
  39. package/dist/wizard.js +35 -56
  40. package/dist/workspace-docs.d.ts +44 -0
  41. package/dist/workspace-docs.js +73 -0
  42. package/package.json +2 -2
  43. package/templates/env.example +33 -23
  44. package/templates/workspace-root/AGENT.md +7 -5
  45. package/templates/workspace-root/ONBOARDING.md +65 -8
  46. package/templates/workspace-root/skills/.github/workflows/pr-to-slack.yml +102 -0
  47. package/templates/workspace-root/skills/CLAUDE.md +24 -6
  48. package/templates/workspace-root/skills/README.md +156 -0
  49. package/templates/workspace-root/skills/backtest-acceptance-gates/SKILL.md +293 -0
  50. package/templates/workspace-root/skills/backtest-acceptance-gates/backtest-acceptance-gates-guide.pdf +0 -0
  51. package/templates/workspace-root/skills/backtest-acceptance-gates/references/evidence-record-template.md +128 -0
  52. package/templates/workspace-root/skills/backtest-acceptance-gates/references/harness-checklist.md +90 -0
  53. package/templates/workspace-root/skills/client-latest/SKILL.md +301 -0
  54. package/templates/workspace-root/skills/client-latest/catchup.command.md +17 -0
  55. package/templates/workspace-root/skills/cloud-devops/SKILL.md +235 -0
  56. package/templates/workspace-root/skills/email-triage-rollout/SKILL.md +181 -0
  57. package/templates/workspace-root/skills/gcloud-cli-setup/SKILL.md +100 -0
  58. package/templates/workspace-root/skills/google-chat-app-setup/SKILL.md +136 -0
  59. package/templates/workspace-root/skills/google-chat-app-setup/google-chat-app-setup-guide.pdf +0 -0
  60. package/templates/workspace-root/skills/house-voice/SKILL.md +80 -4
  61. package/templates/workspace-root/skills/ia-cli/SKILL.md +19 -6
  62. package/templates/workspace-root/skills/installagent-brand-kit/SKILL.md +59 -10
  63. package/templates/workspace-root/skills/installagent-brand-kit/assets/installagent-deck-template.pptx +0 -0
  64. package/templates/workspace-root/skills/installagent-brand-kit/references/deck-guide.md +181 -0
  65. package/templates/workspace-root/skills/installagent-brand-kit/scripts/deck.py +652 -0
  66. package/templates/workspace-root/skills/installagent-brand-kit/scripts/deck_lint.py +201 -0
  67. package/templates/workspace-root/skills/installagent-brand-kit/scripts/logo_raster.py +102 -0
  68. package/templates/workspace-root/skills/installagent-brand-kit/scripts/make_deck_template.py +290 -0
  69. package/templates/workspace-root/skills/salesforce-api-snapshot/SKILL.md +379 -0
  70. package/templates/workspace-root/skills/salesforce-api-snapshot/references/schema-discovery-soql.md +153 -0
  71. package/templates/workspace-root/skills/salesforce-api-snapshot/references/snapshot-storage.md +122 -0
  72. package/templates/workspace-root/skills/salesforce-api-snapshot/salesforce-api-snapshot-guide.pdf +0 -0
  73. package/templates/workspace-root/skills/slack-voice/SKILL.md +158 -0
  74. package/templates/workspace-root/skills/sso-gated-client-app/SKILL.md +337 -0
  75. package/templates/workspace-root/skills/sso-gated-client-app/sso-gated-client-app-guide.pdf +0 -0
  76. package/templates/workspace-root/skills/tech-call-prep/SKILL.md +146 -47
  77. package/templates/workspace-root/skills/vendor-feed-ingestion/SKILL.md +323 -0
  78. package/templates/workspace-root/skills/vendor-feed-ingestion/references/delivery-contract-template.md +110 -0
  79. package/templates/workspace-root/skills/vendor-feed-ingestion/references/feed-guards.md +134 -0
  80. package/templates/workspace-root/skills/vendor-feed-ingestion/vendor-feed-ingestion-guide.pdf +0 -0
@@ -0,0 +1,652 @@
1
+ """Install Agent deck builder — on-brand .pptx for upload to Google Slides.
2
+
3
+ import sys; sys.path.append(".../skills/installagent-brand-kit/scripts")
4
+ from deck import Deck
5
+
6
+ d = Deck(client="Acme Co", date="4 Aug 2026", total=4)
7
+ d.cover("ACME CO", "Where we are, and what we need to decide today",
8
+ "Attendees 4 August 2026 · 60 minutes",
9
+ outcomes=[("A priority order", "we all agree on"), ...])
10
+ s = d.slide("01 · already working", "One thing is live", "Sub-line.")
11
+ d.pipeline(s, [("inbox", "New mail arrives", "Any hour"), ...], accent=3)
12
+ d.callout(s, "The sentence they must remember.", "Supporting clause.")
13
+ d.save("deck.pptx")
14
+
15
+ Then ALWAYS run the linter before handing it over:
16
+
17
+ python deck_lint.py deck.pptx
18
+
19
+ Why this module exists: every branding error worth having is an error someone
20
+ already made by hand. Palette, type, logo, geometry and the ten slide
21
+ archetypes are fixed here so a new deck cannot reintroduce them. Colours come
22
+ from `brand.py` — this file contains no hex literal, and neither should yours.
23
+
24
+ It governs BRAND and LAYOUT only. What a slide *claims* is your problem: check
25
+ every number and status word against a source file before you ship (the client
26
+ repo's CADENCE.md § surface matrix is the process for that).
27
+ """
28
+ from __future__ import annotations
29
+
30
+ from pptx import Presentation
31
+ from pptx.util import Inches, Pt, Emu
32
+ from pptx.dml.color import RGBColor
33
+ from pptx.enum.text import PP_ALIGN, MSO_ANCHOR
34
+ from pptx.enum.shapes import MSO_SHAPE
35
+ from pptx.enum.dml import MSO_LINE_DASH_STYLE
36
+
37
+ import brand
38
+ import logo_raster
39
+
40
+
41
+ def C(hexstr: str) -> RGBColor:
42
+ return RGBColor.from_string(hexstr.lstrip("#").upper())
43
+
44
+
45
+ # ── brand tokens — imported, never retyped ─────────────────────────────────
46
+ RED = C(brand.BRAND) # deep red: primary on white
47
+ RED_SIG = C(brand.BRAND_BRIGHT) # signal red: ATTENTION ONLY, never decoration
48
+ TINT = C(brand.BRAND_TINT)
49
+ ROW = C(brand.ROW_TINT)
50
+ INK = C(brand.INK)
51
+ BODY = C(brand.BODY)
52
+ MUTED = C(brand.MUTED)
53
+ FAINT = C(brand.FAINT)
54
+ LINE = C(brand.LINE)
55
+ GRID = C(brand.GRID)
56
+ SOFT = C(brand.SOFT)
57
+ WHITE = C(brand.WHITE)
58
+
59
+ SANS = "Hanken Grotesk"
60
+ MONO = "JetBrains Mono"
61
+
62
+ # 16:9 stated in EXACT EMU. Inches(13.333) is 12191695 EMU — 305 EMU short of
63
+ # a true 16:9 against a 7.5in height, which makes Google Slides rescale on
64
+ # import. 12192000 is the honest number.
65
+ W, H = Emu(12192000), Inches(7.5)
66
+ L, CW = Inches(0.72), Inches(11.9) # content left edge + usable width
67
+ HAIRLINE = Emu(12700) # thinnest line that survives a
68
+ # projector — 9525 (0.75pt) does not
69
+ BOTTOM_SAFE = H - Inches(0.34) # keep frames clear of the footer
70
+
71
+ TONE = { # semantic → (chip fg, card fill, border)
72
+ "blocking": (RED_SIG, TINT, RED_SIG), # needs the client to act
73
+ "active": (RED, TINT, RED), # we are on it now
74
+ "ready": (RED, WHITE, LINE), # done, waiting on one thing
75
+ "queued": (FAINT, WHITE, LINE), # sequenced, not started
76
+ "neutral": (MUTED, WHITE, LINE),
77
+ }
78
+
79
+
80
+ class Slide:
81
+ """A slide plus a vertical cursor, so archetypes can stack on one page."""
82
+
83
+ def __init__(self, s, y):
84
+ self.s, self.y = s, y
85
+
86
+
87
+ class Deck:
88
+ def __init__(self, *, client: str, date: str, total: int,
89
+ org: str = "Install Agent"):
90
+ self.prs = Presentation()
91
+ self.prs.slide_width, self.prs.slide_height = W, H
92
+ self.footer_text = f"{org} × {client} · {date}"
93
+ self.total, self.n = total, 0
94
+ self._lockup = str(logo_raster.lockup())
95
+ self._mark = str(logo_raster.mark())
96
+
97
+ # ── plumbing ──────────────────────────────────────────────────────────
98
+ def _blank(self, *, cover=False):
99
+ s = self.prs.slides.add_slide(self.prs.slide_layouts[6])
100
+ bg = s.shapes.add_shape(MSO_SHAPE.RECTANGLE, 0, 0, W, H)
101
+ bg.fill.solid(); bg.fill.fore_color.rgb = WHITE
102
+ bg.line.fill.background(); bg.shadow.inherit = False
103
+ if not cover:
104
+ r = s.shapes.add_shape(MSO_SHAPE.RECTANGLE, L, Inches(0.95),
105
+ CW, HAIRLINE)
106
+ r.fill.solid(); r.fill.fore_color.rgb = RED
107
+ r.line.fill.background(); r.shadow.inherit = False
108
+ s.shapes.add_picture(self._mark, Inches(12.63), Inches(0.42),
109
+ height=Inches(0.34))
110
+ self.n += 1
111
+ return s
112
+
113
+ def tb(self, s, x, y, w, h, anchor=MSO_ANCHOR.TOP):
114
+ h = min(h, max(Emu(1), BOTTOM_SAFE - y)) # never overhang the footer
115
+ box = s.shapes.add_textbox(x, y, w, h)
116
+ tf = box.text_frame
117
+ tf.word_wrap = True
118
+ tf.vertical_anchor = anchor
119
+ tf.margin_left = tf.margin_right = 0
120
+ tf.margin_top = tf.margin_bottom = 0
121
+ return tf
122
+
123
+ def para(self, tf, text, size, color, *, font=SANS, bold=False, first=False,
124
+ space_after=6, align=PP_ALIGN.LEFT, italic=False,
125
+ line_spacing=None):
126
+ # NB: never put "\n" in `text` — renderers disagree on whether it
127
+ # breaks. Call para() twice, or let word_wrap do the work.
128
+ p = tf.paragraphs[0] if first else tf.add_paragraph()
129
+ p.alignment = align
130
+ p.space_before = Pt(0)
131
+ p.space_after = Pt(space_after)
132
+ if line_spacing:
133
+ p.line_spacing = line_spacing
134
+ r = p.add_run(); r.text = text.replace("\n", " ")
135
+ r.font.size = Pt(size); r.font.bold = bold; r.font.italic = italic
136
+ r.font.name = font; r.font.color.rgb = color
137
+ return r
138
+
139
+ def runs(self, tf, parts, size, *, first=False, space_after=6,
140
+ gap_glyph=None, glyph_color=None, align=PP_ALIGN.LEFT):
141
+ """parts: [(text, color, bold[, font]), ...] on one paragraph."""
142
+ p = tf.paragraphs[0] if first else tf.add_paragraph()
143
+ p.space_after = Pt(space_after)
144
+ p.alignment = align
145
+ if gap_glyph:
146
+ g = p.add_run(); g.text = gap_glyph + " "
147
+ g.font.size = Pt(size); g.font.bold = True; g.font.name = SANS
148
+ g.font.color.rgb = glyph_color or RED
149
+ for part in parts:
150
+ r = p.add_run(); r.text = part[0].replace("\n", " ")
151
+ r.font.size = Pt(size); r.font.bold = part[2]
152
+ r.font.name = part[3] if len(part) > 3 else SANS
153
+ r.font.color.rgb = part[1]
154
+ return p
155
+
156
+ @staticmethod
157
+ def strike(run):
158
+ """python-pptx exposes no strikethrough; set it on the run props."""
159
+ run.font._rPr.set("strike", "sngStrike")
160
+
161
+ def card(self, s, x, y, w, h, *, fill=WHITE, line=LINE, width=0.75):
162
+ c = s.shapes.add_shape(MSO_SHAPE.ROUNDED_RECTANGLE, x, y, w, h)
163
+ c.fill.solid(); c.fill.fore_color.rgb = fill
164
+ if line is None:
165
+ c.line.fill.background()
166
+ else:
167
+ c.line.color.rgb = line; c.line.width = Pt(width)
168
+ c.shadow.inherit = False; c.adjustments[0] = 0.05
169
+ return c
170
+
171
+ def kicker(self, s, x, y, text, *, w=Inches(5.0), color=FAINT, size=9.5,
172
+ align=PP_ALIGN.LEFT):
173
+ """Small mono all-caps label. Always pass `w` — the default overhangs."""
174
+ tf = self.tb(s, x, y, w, Inches(0.24))
175
+ self.para(tf, text.upper(), size, color, font=MONO, bold=True,
176
+ first=True, space_after=0, align=align)
177
+
178
+ def pill(self, s, x, y, text, *, fill=SOFT, fg=MUTED, border=None,
179
+ size=8.5, h=Inches(0.25), w=None):
180
+ if w is None:
181
+ w = Inches(0.071 * size / 8.5 * len(text) + 0.30)
182
+ p = s.shapes.add_shape(MSO_SHAPE.ROUNDED_RECTANGLE, x, y, w, h)
183
+ p.fill.solid(); p.fill.fore_color.rgb = fill
184
+ if border is None:
185
+ p.line.fill.background()
186
+ else:
187
+ p.line.color.rgb = border; p.line.width = Pt(0.75)
188
+ p.shadow.inherit = False; p.adjustments[0] = 0.5
189
+ tf = self.tb(s, x, y + Inches(0.045), w, Inches(0.2))
190
+ self.para(tf, text, size, fg, font=MONO, bold=True, first=True,
191
+ align=PP_ALIGN.CENTER, space_after=0)
192
+ return x + w
193
+
194
+ def badge(self, s, x, y, label, *, d=Inches(0.44), fill=RED, fg=WHITE,
195
+ size=15):
196
+ o = s.shapes.add_shape(MSO_SHAPE.OVAL, x, y, d, d)
197
+ o.fill.solid(); o.fill.fore_color.rgb = fill
198
+ o.line.fill.background(); o.shadow.inherit = False
199
+ tf = self.tb(s, x, y + d / 2 - Inches(0.115), d, Inches(0.24))
200
+ self.para(tf, label, size, fg, font=MONO, bold=True, first=True,
201
+ align=PP_ALIGN.CENTER, space_after=0)
202
+ return o
203
+
204
+ def arrow(self, s, x, y, *, w=Inches(0.3), h=Inches(0.15), color=RED):
205
+ a = s.shapes.add_shape(MSO_SHAPE.RIGHT_ARROW, x, y, w, h)
206
+ a.fill.solid(); a.fill.fore_color.rgb = color
207
+ a.line.fill.background(); a.shadow.inherit = False
208
+ return a
209
+
210
+ def rule(self, s, x, y, w, *, color=LINE, thick=HAIRLINE):
211
+ ln = s.shapes.add_shape(MSO_SHAPE.RECTANGLE, x, y, w, thick)
212
+ ln.fill.solid(); ln.fill.fore_color.rgb = color
213
+ ln.line.fill.background(); ln.shadow.inherit = False
214
+
215
+ def bar(self, s, x, y, w, h, fill, *, dashed=False, border=None,
216
+ corner=0.5):
217
+ shp = s.shapes.add_shape(MSO_SHAPE.ROUNDED_RECTANGLE, x, y, w, h)
218
+ shp.fill.solid(); shp.fill.fore_color.rgb = fill
219
+ if border is None:
220
+ shp.line.fill.background()
221
+ else:
222
+ shp.line.color.rgb = border; shp.line.width = Pt(1)
223
+ if dashed:
224
+ shp.line.dash_style = MSO_LINE_DASH_STYLE.DASH
225
+ shp.shadow.inherit = False; shp.adjustments[0] = corner
226
+ return shp
227
+
228
+ def stat(self, s, x, y, w, big, small, *, size=30, color=RED):
229
+ tf = self.tb(s, x, y, w, Inches(0.95))
230
+ self.para(tf, big, size, color, font=MONO, bold=True, first=True,
231
+ space_after=1)
232
+ self.para(tf, small, 11, BODY, space_after=0, line_spacing=1.0)
233
+
234
+ def footer(self, s, note=""):
235
+ tf = self.tb(s, L, Inches(6.99), Inches(11.0), Inches(0.3))
236
+ parts = [(self.footer_text, FAINT, False, MONO)]
237
+ if note:
238
+ parts.append((" · " + note, FAINT, False, MONO))
239
+ self.runs(tf, parts, 9, first=True, space_after=0)
240
+ r = self.tb(s, Inches(12.1), Inches(6.99), Inches(0.6), Inches(0.3))
241
+ self.para(r, f"{self.n}/{self.total}", 9, RED, font=MONO, bold=True,
242
+ first=True, align=PP_ALIGN.RIGHT, space_after=0)
243
+
244
+ # ── archetype 1: cover ────────────────────────────────────────────────
245
+ def cover(self, eyebrow, title, meta, *, outcomes=(), note=""):
246
+ s = self._blank(cover=True)
247
+ band = s.shapes.add_shape(MSO_SHAPE.RECTANGLE, 0, 0, Inches(0.16), H)
248
+ band.fill.solid(); band.fill.fore_color.rgb = RED
249
+ band.line.fill.background(); band.shadow.inherit = False
250
+ s.shapes.add_picture(self._lockup, Inches(0.86), Inches(0.74),
251
+ height=Inches(0.6))
252
+ tf = self.tb(s, Inches(0.86), Inches(2.05), Inches(11.6), Inches(2.4))
253
+ self.para(tf, eyebrow.upper(), 11.5, RED, font=MONO, bold=True,
254
+ first=True, space_after=16)
255
+ self.para(tf, title, 40, INK, bold=True, space_after=14,
256
+ line_spacing=1.02)
257
+ self.para(tf, meta, 14, MUTED, space_after=0)
258
+ if outcomes:
259
+ self.kicker(s, Inches(0.86), Inches(4.52), "By the end of this hour",
260
+ w=Inches(6.0))
261
+ tw, tg = Inches(3.75), Inches(0.255)
262
+ for i, (head, line) in enumerate(outcomes[:3]):
263
+ x = Inches(0.86) + i * (tw + tg)
264
+ self.card(s, x, Inches(4.84), tw, Inches(1.72), fill=SOFT,
265
+ line=None)
266
+ self.badge(s, x + Inches(0.26), Inches(5.06), str(i + 1),
267
+ d=Inches(0.4), size=14)
268
+ tfc = self.tb(s, x + Inches(0.26), Inches(5.62),
269
+ tw - Inches(0.52), Inches(0.9))
270
+ self.para(tfc, head, 16, INK, bold=True, first=True,
271
+ space_after=3)
272
+ self.para(tfc, line, 11, BODY, space_after=0, line_spacing=1.0)
273
+ self.footer(s, note)
274
+ return Slide(s, Inches(2.24))
275
+
276
+ # ── every other slide starts here ─────────────────────────────────────
277
+ def slide(self, eyebrow, title, sub=None, *, note=""):
278
+ s = self._blank()
279
+ tf = self.tb(s, L, Inches(0.36), Inches(11.6), Inches(0.5))
280
+ self.para(tf, eyebrow.upper(), 10.5, RED, font=MONO, bold=True,
281
+ first=True, space_after=0)
282
+ tf2 = self.tb(s, L, Inches(1.22), CW, Inches(1.2))
283
+ self.para(tf2, title, 31, INK, bold=True, first=True,
284
+ space_after=5 if sub else 0)
285
+ if sub:
286
+ self.para(tf2, sub, 13.5, MUTED, space_after=0)
287
+ self.footer(s, note)
288
+ return Slide(s, Inches(2.66) if sub else Inches(2.24))
289
+
290
+ # ── archetype 2: pipeline of steps ────────────────────────────────────
291
+ def pipeline(self, sl, steps, *, accent=None, h=Inches(1.2)):
292
+ n = len(steps)
293
+ gap = Inches(0.44)
294
+ bw = int((CW - gap * (n - 1)) / n)
295
+ for i, (kick, title, sub) in enumerate(steps):
296
+ x = L + i * (bw + gap)
297
+ hot = (i == accent)
298
+ self.card(sl.s, x, sl.y, bw, h, fill=TINT if hot else SOFT,
299
+ line=RED if hot else LINE, width=1.0 if hot else 0.75)
300
+ self.kicker(sl.s, x + Inches(0.2), sl.y + Inches(0.16), kick,
301
+ w=bw - Inches(0.4), color=RED if hot else FAINT)
302
+ tfc = self.tb(sl.s, x + Inches(0.2), sl.y + Inches(0.44),
303
+ bw - Inches(0.4), h - Inches(0.58))
304
+ self.para(tfc, title, 13, INK, bold=True, first=True,
305
+ space_after=4 if sub else 0, line_spacing=0.95)
306
+ if sub:
307
+ self.para(tfc, sub, 10.5, MUTED, space_after=0,
308
+ line_spacing=0.95)
309
+ if i < n - 1:
310
+ self.arrow(sl.s, x + bw + Inches(0.07), sl.y + h / 2 - Inches(0.08))
311
+ sl.y += h + Inches(0.38)
312
+
313
+ # ── archetype 3: progression, with "you are here" filled ──────────────
314
+ def ladder(self, sl, stages, *, label=None):
315
+ if label:
316
+ self.kicker(sl.s, L, sl.y, label, w=Inches(7.0))
317
+ sl.y += Inches(0.32)
318
+ n = len(stages)
319
+ gap = Inches(0.62)
320
+ bw = int((CW - gap * (n - 1)) / n)
321
+ for i, (title, sub, live) in enumerate(stages):
322
+ x = L + i * (bw + gap)
323
+ self.bar(sl.s, x, sl.y, bw, Inches(0.62), RED if live else SOFT,
324
+ border=None if live else LINE)
325
+ tfc = self.tb(sl.s, x + Inches(0.24), sl.y + Inches(0.12),
326
+ bw - Inches(0.48), Inches(0.44))
327
+ self.para(tfc, ("✓ " if live else "") + title, 13.5,
328
+ WHITE if live else INK, bold=True, first=True,
329
+ space_after=1)
330
+ self.para(tfc, sub, 10, WHITE if live else FAINT, font=MONO,
331
+ space_after=0)
332
+ if i < n - 1:
333
+ self.arrow(sl.s, x + bw + Inches(0.16), sl.y + Inches(0.24),
334
+ w=Inches(0.3), h=Inches(0.16))
335
+ sl.y += Inches(1.0)
336
+
337
+ # ── archetype 4: numbered cards with a status chip ────────────────────
338
+ def cards(self, sl, items, *, h=Inches(3.34)):
339
+ """items: [(numeral, name, description, chip_text, tone), ...]"""
340
+ n = len(items)
341
+ gap = Inches(0.1)
342
+ cw = int((CW - gap * (n - 1)) / n)
343
+ for i, (num, name, desc, chip, tone) in enumerate(items):
344
+ fg, fill, border = TONE[tone]
345
+ lead = tone in ("blocking", "active")
346
+ x = L + i * (cw + gap)
347
+ self.card(sl.s, x, sl.y, cw, h, fill=fill, line=border,
348
+ width=1.25 if lead else 0.75)
349
+ tfn = self.tb(sl.s, x + Inches(0.26), sl.y + Inches(0.2),
350
+ cw - Inches(0.52), Inches(0.8))
351
+ self.para(tfn, str(num), 44, RED if lead else LINE, font=MONO,
352
+ bold=True, first=True, space_after=0)
353
+ tfc = self.tb(sl.s, x + Inches(0.26), sl.y + Inches(1.0),
354
+ cw - Inches(0.52), Inches(1.9))
355
+ self.para(tfc, name, 16.5, INK, bold=True, first=True,
356
+ space_after=8, line_spacing=0.98)
357
+ self.para(tfc, desc, 11, BODY, space_after=0, line_spacing=1.02)
358
+ self.pill(sl.s, x + Inches(0.26), sl.y + h - Inches(0.48), chip,
359
+ fg=fg, fill=WHITE if lead else SOFT,
360
+ border=border if lead else None)
361
+ sl.y += h + Inches(0.2)
362
+
363
+ # ── archetype 5: flow with a struck-out, cut step ─────────────────────
364
+ def flow(self, sl, steps, *, cut=None, h=Inches(1.24)):
365
+ """steps: [(kicker, title, sub), ...]. `cut` = index to strike out."""
366
+ n = len(steps)
367
+ gap = Inches(0.25)
368
+ bw = int((CW - gap * (n - 1)) / n)
369
+ for i, (kick, title, sub) in enumerate(steps):
370
+ x = L + i * (bw + gap)
371
+ dead = (i == cut)
372
+ self.card(sl.s, x, sl.y, bw, h, fill=WHITE if dead else SOFT,
373
+ line=RED_SIG if dead else LINE,
374
+ width=1.0 if dead else 0.75)
375
+ self.kicker(sl.s, x + Inches(0.2), sl.y + Inches(0.16), kick,
376
+ w=bw - Inches(0.4), color=RED if dead else FAINT)
377
+ tfc = self.tb(sl.s, x + Inches(0.2), sl.y + Inches(0.44),
378
+ bw - Inches(0.4), h - Inches(0.58))
379
+ r = self.para(tfc, title, 13, INK, bold=True, first=True,
380
+ space_after=4 if sub else 0, line_spacing=0.95)
381
+ if dead:
382
+ self.strike(r)
383
+ self.pill(sl.s, x + bw - Inches(1.06), sl.y - Inches(0.16),
384
+ "✕ CUT", fill=RED_SIG, fg=WHITE, size=9)
385
+ if sub:
386
+ self.para(tfc, sub, 10.5, MUTED, space_after=0,
387
+ line_spacing=0.95)
388
+ if i < n - 1:
389
+ # grey the arrows either side of a cut step, so the flow
390
+ # visibly stops there instead of appearing to pass through
391
+ near_cut = cut is not None and i in (cut - 1, cut)
392
+ self.arrow(sl.s, x + bw, sl.y + h / 2 - Inches(0.08),
393
+ color=LINE if near_cut else RED)
394
+ sl.y += h + Inches(0.42)
395
+
396
+ # ── archetype 6: proportional gantt ──────────────────────────────────
397
+ def gantt(self, sl, stages, *, days=20, label_w=Inches(2.18),
398
+ attention=None):
399
+ """stages: [(name, note, start_day, min_days, max_days), ...]
400
+
401
+ Solid bar = committed minimum; dashed extension = range if it runs
402
+ long. `attention` names the one stage rendered in signal red.
403
+ """
404
+ ax = L + label_w
405
+ aw = CW - label_w - Inches(1.22) # room for the day label
406
+ dpx = aw / days
407
+ rowh = Inches(0.62)
408
+ chart_h = rowh * len(stages) + Inches(0.16)
409
+ for d in range(5, days + 1, 5):
410
+ gx = ax + int(dpx * d)
411
+ v = sl.s.shapes.add_shape(MSO_SHAPE.RECTANGLE, gx,
412
+ sl.y + Inches(0.14), HAIRLINE, chart_h)
413
+ v.fill.solid(); v.fill.fore_color.rgb = LINE
414
+ v.line.fill.background(); v.shadow.inherit = False
415
+ self.kicker(sl.s, gx - Inches(0.4), sl.y - Inches(0.08),
416
+ f"day {d}", w=Inches(0.8), size=8.5,
417
+ align=PP_ALIGN.CENTER)
418
+ for i, (name, note, start, dmin, dmax) in enumerate(stages):
419
+ ry = sl.y + Inches(0.56) + i * rowh
420
+ tfr = self.tb(sl.s, L, ry, label_w - Inches(0.13), Inches(0.5))
421
+ self.para(tfr, name, 13.5, INK, bold=True, first=True,
422
+ space_after=1)
423
+ self.para(tfr, note, 9.5, MUTED, space_after=0, line_spacing=0.95)
424
+ hot = RED_SIG if name == attention else RED
425
+ bx = ax + int(dpx * start)
426
+ self.bar(sl.s, bx, ry + Inches(0.04), int(dpx * dmin),
427
+ Inches(0.32), hot, corner=0.14)
428
+ if dmax > dmin:
429
+ self.bar(sl.s, bx + int(dpx * dmin), ry + Inches(0.04),
430
+ int(dpx * (dmax - dmin)), Inches(0.32), WHITE,
431
+ border=hot, dashed=True, corner=0.14)
432
+ tfd = self.tb(sl.s, bx + int(dpx * dmax) + Inches(0.12),
433
+ ry + Inches(0.08), Inches(1.1), Inches(0.26))
434
+ self.para(tfd, f"{dmin}–{dmax} d", 10.5, INK, font=MONO, bold=True,
435
+ first=True, space_after=0)
436
+ ly = sl.y + Inches(0.62) + rowh * len(stages)
437
+ # swatches are drawn, not typed: ▮/▯ do not resolve in every font
438
+ self.bar(sl.s, ax, ly + Inches(0.03), Inches(0.24), Inches(0.13), RED,
439
+ corner=0.14)
440
+ self.kicker(sl.s, ax + Inches(0.34), ly, "committed minimum",
441
+ w=Inches(1.6), color=RED, size=8.5)
442
+ self.bar(sl.s, ax + Inches(2.1), ly + Inches(0.03), Inches(0.24),
443
+ Inches(0.13), WHITE, border=MUTED, dashed=True, corner=0.14)
444
+ self.kicker(sl.s, ax + Inches(2.44), ly, "range if it runs long",
445
+ w=Inches(1.8), color=MUTED, size=8.5)
446
+ sl.y = ly + Inches(0.42)
447
+
448
+ # ── archetype 7: tile grid (access asks, requirements, risks) ─────────
449
+ def tiles(self, sl, items, *, cols=4, h=Inches(1.94)):
450
+ """items: [(glyph, title, detail, owner_chip, blocking_bool), ...]"""
451
+ gap = Inches(0.2)
452
+ tw = int((CW - gap * (cols - 1)) / cols)
453
+ for i, (glyph, title, detail, owner, blocking) in enumerate(items):
454
+ col, row = i % cols, i // cols
455
+ x = L + col * (tw + gap)
456
+ ty = sl.y + row * (h + Inches(0.18))
457
+ self.card(sl.s, x, ty, tw, h, fill=TINT if blocking else WHITE,
458
+ line=RED_SIG if blocking else LINE,
459
+ width=1.25 if blocking else 0.75)
460
+ tfg = self.tb(sl.s, x + Inches(0.22), ty + Inches(0.18),
461
+ Inches(0.34), Inches(0.3))
462
+ self.para(tfg, glyph, 14, RED_SIG if blocking else RED, bold=True,
463
+ first=True, space_after=0)
464
+ tfc = self.tb(sl.s, x + Inches(0.22), ty + Inches(0.5),
465
+ tw - Inches(0.44), h - Inches(0.9))
466
+ self.para(tfc, title, 12.5, INK, bold=True, first=True,
467
+ space_after=5, line_spacing=0.96)
468
+ self.para(tfc, detail, 10, BODY, space_after=0, line_spacing=1.0)
469
+ self.pill(sl.s, x + Inches(0.22), ty + h - Inches(0.4), owner,
470
+ size=7.5, fill=WHITE if blocking else SOFT,
471
+ fg=RED_SIG if blocking else MUTED,
472
+ border=RED_SIG if blocking else None)
473
+ rows = (len(items) + cols - 1) // cols
474
+ sl.y += rows * (h + Inches(0.18))
475
+
476
+ # ── archetype 8: decisions, each with its default ────────────────────
477
+ def decisions(self, sl, items, *, cols=2, h=Inches(1.06),
478
+ default_label="if not decided today"):
479
+ gap = Inches(0.2)
480
+ dw = int((CW - gap * (cols - 1)) / cols)
481
+ for i, (question, default) in enumerate(items):
482
+ col, row = i % cols, i // cols
483
+ x = L + col * (dw + gap)
484
+ dy = sl.y + row * (h + Inches(0.2))
485
+ self.card(sl.s, x, dy, dw, h)
486
+ self.badge(sl.s, x + Inches(0.26), dy + Inches(0.24), "?",
487
+ d=Inches(0.36), fill=TINT, fg=RED, size=13)
488
+ tfc = self.tb(sl.s, x + Inches(0.76), dy + Inches(0.22),
489
+ dw - Inches(1.02), Inches(0.9))
490
+ self.para(tfc, question, 14, INK, bold=True, first=True,
491
+ space_after=6)
492
+ self.runs(tfc, [(default_label + " — ", FAINT, True, MONO),
493
+ (default, MUTED, False)], 10.5, space_after=0)
494
+ rows = (len(items) + cols - 1) // cols
495
+ sl.y += rows * (h + Inches(0.2))
496
+
497
+ # ── archetype 9: chat mock (a demo without a screenshot) ─────────────
498
+ def chat(self, sl, *, channel, question, answer, citation=None,
499
+ w=Inches(6.9), h=Inches(3.6), fallback=None,
500
+ label="example exchange"):
501
+ s = sl.s
502
+ self.card(s, L, sl.y, w, h)
503
+ strip = s.shapes.add_shape(MSO_SHAPE.RECTANGLE, L + Inches(0.02),
504
+ sl.y + Inches(0.02), w - Inches(0.04),
505
+ Inches(0.42))
506
+ strip.fill.solid(); strip.fill.fore_color.rgb = SOFT
507
+ strip.line.fill.background(); strip.shadow.inherit = False
508
+ self.kicker(s, L + Inches(0.26), sl.y + Inches(0.13), channel,
509
+ w=w - Inches(2.6), color=MUTED)
510
+ # An invented exchange must be labelled as one, always.
511
+ self.kicker(s, L + w - Inches(2.3), sl.y + Inches(0.13), label,
512
+ w=Inches(2.04), color=FAINT, size=8.5,
513
+ align=PP_ALIGN.RIGHT)
514
+ ask = self.bar(s, L + Inches(1.5), sl.y + Inches(0.66),
515
+ w - Inches(1.76), Inches(0.5), SOFT, corner=0.28)
516
+ tfa = self.tb(s, L + Inches(1.72), sl.y + Inches(0.79),
517
+ w - Inches(2.2), Inches(0.3))
518
+ self.para(tfa, question, 12.5, INK, first=True, space_after=0,
519
+ align=PP_ALIGN.RIGHT)
520
+ self.bar(s, L + Inches(0.26), sl.y + Inches(1.32), w - Inches(1.4),
521
+ Inches(1.5), TINT, corner=0.09)
522
+ s.shapes.add_picture(self._mark, L + Inches(0.42), sl.y + Inches(1.5),
523
+ height=Inches(0.24))
524
+ tfb = self.tb(s, L + Inches(0.42), sl.y + Inches(1.86),
525
+ w - Inches(1.72), Inches(1.0))
526
+ self.para(tfb, answer, 12.5, INK, first=True, space_after=8,
527
+ line_spacing=1.02)
528
+ if citation:
529
+ self.pill(s, L + Inches(0.42), sl.y + Inches(2.44), citation,
530
+ fill=WHITE, fg=RED, border=RED)
531
+ if fallback:
532
+ tfe = self.tb(s, L + Inches(0.26), sl.y + Inches(3.02),
533
+ w - Inches(0.6), Inches(0.4))
534
+ self.runs(tfe, [(fallback[0], INK, True), (fallback[1], BODY, False)],
535
+ 11.5, first=True, space_after=0, gap_glyph="→",
536
+ glyph_color=RED)
537
+ return L + w + Inches(0.2) # x where a right-hand panel starts
538
+
539
+ # ── archetype 10: kanban by deadline ─────────────────────────────────
540
+ def kanban(self, sl, columns, *, cardh=Inches(0.8), step=Inches(0.88)):
541
+ """columns: [(title, accent, [(num, text, owner, urgent), ...]), ...]"""
542
+ n = len(columns)
543
+ gap = Inches(0.205)
544
+ cw = int((CW - gap * (n - 1)) / n)
545
+ for ci, (title, accent, items) in enumerate(columns):
546
+ x = L + ci * (cw + gap)
547
+ hb = sl.s.shapes.add_shape(MSO_SHAPE.ROUNDED_RECTANGLE, x, sl.y,
548
+ cw, Inches(0.4))
549
+ hb.fill.solid()
550
+ hb.fill.fore_color.rgb = SOFT if accent is MUTED else TINT
551
+ hb.line.fill.background(); hb.shadow.inherit = False
552
+ hb.adjustments[0] = 0.22
553
+ self.kicker(sl.s, x, sl.y + Inches(0.11), title, w=cw,
554
+ color=accent, size=10, align=PP_ALIGN.CENTER)
555
+ for ii, (num, text, owner, urgent) in enumerate(items):
556
+ iy = sl.y + Inches(0.54) + ii * step
557
+ self.card(sl.s, x, iy, cw, cardh,
558
+ line=RED_SIG if urgent else LINE,
559
+ width=1.25 if urgent else 0.75)
560
+ self.badge(sl.s, x + Inches(0.2), iy + Inches(0.14), str(num),
561
+ d=Inches(0.32), fill=RED_SIG if urgent else RED,
562
+ size=11)
563
+ tfc = self.tb(sl.s, x + Inches(0.62), iy + Inches(0.13),
564
+ cw - Inches(0.84), Inches(0.62))
565
+ self.para(tfc, text, 11.5, INK, bold=True, first=True,
566
+ space_after=3, line_spacing=0.96)
567
+ self.runs(tfc, [(("⚠ " if urgent else "") + owner,
568
+ RED_SIG if urgent else FAINT, True, MONO)],
569
+ 8.5, space_after=0)
570
+ bottoms = [(L + ci * (cw + gap),
571
+ sl.y + Inches(0.54) + len(c[2]) * step, cw)
572
+ for ci, c in enumerate(columns)]
573
+ deepest = max(len(c[2]) for c in columns)
574
+ sl.y += Inches(0.54) + deepest * step
575
+ return bottoms # [(x, bottom_y, width), ...] per column
576
+
577
+ # ── supporting bits ──────────────────────────────────────────────────
578
+ def callout(self, sl, bold, rest="", *, y=None, h=Inches(0.86)):
579
+ y = sl.y if y is None else y
580
+ self.card(sl.s, L, y, CW, h, fill=TINT, line=RED)
581
+ tfc = self.tb(sl.s, L + Inches(0.3), y + Inches(0.16),
582
+ CW - Inches(0.6), h - Inches(0.3))
583
+ parts = [(bold, INK, True)]
584
+ if rest:
585
+ parts.append((" " + rest, BODY, False))
586
+ self.runs(tfc, parts, 12.5, first=True, space_after=0)
587
+ sl.y = y + h + Inches(0.2)
588
+
589
+ def question_band(self, sl, lead, question, *, y=None):
590
+ y = sl.y if y is None else y
591
+ self.card(sl.s, L, y, CW, Inches(0.66), fill=SOFT, line=None)
592
+ tfx = self.tb(sl.s, L + Inches(0.3), y + Inches(0.17),
593
+ CW - Inches(0.6), Inches(0.36))
594
+ self.runs(tfx, [(lead + " ", BODY, False), (question, INK, True)],
595
+ 14, first=True, space_after=0)
596
+ sl.y = y + Inches(0.86)
597
+
598
+ def panel(self, sl, *, w=Inches(3.55), h=Inches(4.28), fill=SOFT,
599
+ line=None):
600
+ """A left-hand card; returns (x, y, w) of its content box and the x
601
+ where the right-hand free area begins (for a bespoke diagram)."""
602
+ self.card(sl.s, L, sl.y, w, h, fill=fill, line=line)
603
+ return (L + Inches(0.28), sl.y + Inches(0.2), w - Inches(0.56),
604
+ L + w + Inches(0.28))
605
+
606
+ def table(self, sl, widths, rows, *, size=11.5, row_h=Inches(0.42),
607
+ zebra=True):
608
+ """rows[0] is the header. Cell = str | (text, color[, bold[, font]])."""
609
+ x, y = L, sl.y
610
+ total_w = Inches(sum(widths))
611
+ band = sl.s.shapes.add_shape(MSO_SHAPE.RECTANGLE, x, y, total_w,
612
+ Inches(0.32))
613
+ band.fill.solid(); band.fill.fore_color.rgb = TINT
614
+ band.line.fill.background(); band.shadow.inherit = False
615
+ cy = y
616
+ for ri, row in enumerate(rows):
617
+ if ri and zebra and ri % 2 == 0:
618
+ z = sl.s.shapes.add_shape(MSO_SHAPE.RECTANGLE, x, cy, total_w,
619
+ row_h)
620
+ z.fill.solid(); z.fill.fore_color.rgb = ROW
621
+ z.line.fill.background(); z.shadow.inherit = False
622
+ cx = x
623
+ for ci, cell in enumerate(row):
624
+ cwid = Inches(widths[ci])
625
+ if isinstance(cell, tuple):
626
+ txt, col = cell[0], cell[1]
627
+ bold = cell[2] if len(cell) > 2 else False
628
+ fnt = cell[3] if len(cell) > 3 else SANS
629
+ else:
630
+ txt, col, bold, fnt = cell, BODY, False, SANS
631
+ tfc = self.tb(sl.s, cx + Inches(0.09), cy + Inches(0.07),
632
+ cwid - Inches(0.2), row_h)
633
+ if ri == 0:
634
+ self.para(tfc, txt.upper(), 9.5, RED, font=MONO, bold=True,
635
+ first=True, space_after=0)
636
+ else:
637
+ self.para(tfc, txt, size, col, font=fnt, bold=bold,
638
+ first=True, space_after=0)
639
+ cx += cwid
640
+ cy += Inches(0.32) if ri == 0 else row_h
641
+ if ri:
642
+ self.rule(sl.s, x, cy, total_w, color=GRID)
643
+ sl.y = cy + Inches(0.2)
644
+
645
+ def save(self, path):
646
+ if self.n != self.total:
647
+ raise ValueError(
648
+ f"Deck(total={self.total}) but {self.n} slides were built — the "
649
+ f"footer page numbers would lie. Fix `total`."
650
+ )
651
+ self.prs.save(str(path))
652
+ return path