@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
@@ -8,7 +8,11 @@ description: >-
8
8
  jargon, confident on value but honestly hedged on numbers, the
9
9
  name-the-objection-then-contrast structure, a one-word-verdict-then-explain
10
10
  FAQ pattern, and a short list of signature phrases to reuse rather than
11
- paraphrase. Use this WHENEVER writing or reviewing client-facing sentences,
11
+ paraphrase. Includes a dedicated SLACK section pulled from the account
12
+ owner's real client messages — greeting/bullets/ask/enthusiasm skeleton,
13
+ his signature phrases, hyphens-not-em-dashes, and emoji as status markers —
14
+ which takes precedence over the marketing register when drafting a client
15
+ Slack reply. Use this WHENEVER writing or reviewing client-facing sentences,
12
16
  or someone says "make this sound like us", "in our voice", "match the
13
17
  website tone", "does this read on-brand", "tighten this copy", "too
14
18
  jargon-y". Reach for it even without the word "skill". Position-agnostic —
@@ -105,6 +109,69 @@ references to an AI system itself.)
105
109
  automation builds." A number or a named institution always beats an
106
110
  adjective like "world-class" used alone.
107
111
 
112
+ ## Slack, specifically — how the account owner actually writes
113
+
114
+ The landing page is the *marketing* register. Day-to-day client Slack is a
115
+ different, warmer register, and it has its own consistent shape. Pulled from
116
+ Angello's real messages across `#client-jared-tomseth`,
117
+ `#client-behaviatherapy-team`, `#client-carvision` and `#client-iloveanthonys`,
118
+ July 2026. When drafting a Slack message for a client, match **this** section
119
+ first and the landing-page pillars second.
120
+
121
+ > **Client only.** This register is for a message a client reads. For an
122
+ > internal message — a teammate DM, `#team-techs`, a status post — use
123
+ > `slack-voice` instead: no greeting, no warmth, lead with the link or the
124
+ > number. Applying this section internally is what produced the DM that got
125
+ > "Bro, can we please use english" on 2026-08-11.
126
+
127
+ **The reliable skeleton of a substantive message:**
128
+
129
+ 1. Warm one-line greeting with the person's @name
130
+ 2. One line of gratitude or momentum — *"thank you for taking the time"*,
131
+ *"Really enjoyed the call today"*, *"thank you for sending everything over
132
+ quickly"*
133
+ 3. The substance, as **bullets** (`•`, sub-bullets `◦`) or a numbered list —
134
+ never long paragraphs
135
+ 4. An explicit, short ask — often literally headed *"Two questions for you:"*
136
+ 5. Close on next step + genuine enthusiasm — *"Excited to get going on this"*
137
+
138
+ **Openers actually used:** "Morning [name] -", "Good morning!", "Hi [name]!!",
139
+ "Hey [name]!", "Heyo", "Gm!", "Thanks for taking the time to speak today".
140
+
141
+ **Signature phrases — reuse verbatim:**
142
+
143
+ - "let me know if you have any questions" / "As always, let me know if any
144
+ questions or concerns"
145
+ - "please don't hesitate to reach out"
146
+ - "I'll reach out if I find I missed anything"
147
+ - "thank you for taking the time"
148
+ - "Excited to get going on this" / "excited to start tackling all this"
149
+ - "With that said, ..." · "Regarding [X], ..." · "As for [X], ..." · "Lastly, ..."
150
+ - "worth noting ..."
151
+ - "I prefer giving conservative timelines so I estimate [date]"
152
+
153
+ **Mechanics that make it sound like him and not like a bot:**
154
+
155
+ - **Hyphens, not em dashes.** He writes " - " where a writer would use "—".
156
+ This is the single most recognisable tell. Do not "upgrade" his dashes.
157
+ - **Emoji, used as punctuation and as status markers.** 🫡 is his most frequent
158
+ sign-off beat; also 🙂 🙏 🎉 ⚡ 👀. In update lists he uses ✅ (done), ✍️ (in
159
+ progress), 🏁 (queued), 🟡 (deferred) as row markers.
160
+ - **"We" for the company's work, "I" for his own actions.** "We'll get to work"
161
+ but "I'll send over everything we spoke about tonight."
162
+ - **Light informality is on-voice**, including the occasional lowercase start
163
+ and clipped line ("awesome, thank you -"). Don't over-polish it into
164
+ corporate register.
165
+ - **Conservative on dates, by explicit policy.** He says he prefers
166
+ conservative timelines and then names one — this is the Slack form of the
167
+ landing page's hedging pillar.
168
+ - **Asks for an explicit ack** when something matters: *"Give me a ✅ once
169
+ you've read the message"*.
170
+
171
+ **What he does not do:** long unbroken paragraphs, headers inside a Slack
172
+ message, bold-heavy formatting, hedging apologies, or hype adjectives. Bad
173
+ news is delivered plainly and immediately, then followed by the plan.
174
+
108
175
  ## Quick before/after
109
176
 
110
177
  > Jargon draft: "Our AI-powered platform leverages seamless automation to
@@ -148,11 +215,20 @@ references to an AI system itself.)
148
215
  ("most," "typically," a range) rather than promised outright.
149
216
  - [ ] Signature phrases ("at a fraction of the cost of a full-time hire")
150
217
  reused verbatim, not paraphrased.
218
+ - [ ] **If it's a client Slack message**: greeting → bullets → explicit ask →
219
+ next step + enthusiasm; hyphens not em dashes; no headers or heavy bold;
220
+ at least one of his signature closers.
151
221
  - [ ] If this is going somewhere permanent, spot-check
152
222
  `references/source-copy.md` (or the live page) hasn't drifted.
153
223
 
154
224
  ## Keeping it in sync
155
225
 
156
- The landing page is the source of truth, not this skill. If
157
- `installagent.com/get-started` copy changes materially, re-pull it into
158
- `references/source-copy.md` and update the patterns above in the same pass.
226
+ The landing page is the source of truth for the marketing register, not this
227
+ skill. If `installagent.com/get-started` copy changes materially, re-pull it
228
+ into `references/source-copy.md` and update the patterns above in the same pass.
229
+
230
+ The **Slack section** has a different source of truth: the account owner's own
231
+ messages in the live `#client-*` channels. It was last pulled 2026-07-31. If his
232
+ writing drifts — or if someone else starts owning client channels — re-sample a
233
+ few recent substantive messages per channel and update that section rather than
234
+ letting the two diverge silently.
@@ -31,8 +31,9 @@ secrets).
31
31
  | The task is… | Run |
32
32
  |---|---|
33
33
  | Set up a machine from nothing / onboard a technician | `ia wizard <dir>` (clones every team repo + root docs + `.env`) |
34
- | Converge an existing workspace with the canonical one | `ia wizard <dir> --update` (ff-only pulls + refresh drifted root docs) |
35
- | "Is my environment OK?" / missing env vars / broken setup | `ia doctor [-w <dir>]` — every gap comes with a fix-it line |
34
+ | Pull every repo up to date (team **and** client repos) | `ia sync [<dir>]` — ff-only; `--docs` also refreshes root docs/skills/`.env.example` |
35
+ | Converge an existing workspace with the canonical one | `ia wizard <dir> --update` (ff-only pulls + refresh drifted root docs; prefer `ia sync`, which also covers `clients/client-*`) |
36
+ | "Is my environment OK?" / missing env vars / broken setup | `ia doctor [-w <dir>]` — every gap comes with a fix-it line; `--all` for every check |
36
37
  | Who is client X / latest calls / what shipped? | `ia client <slug>` |
37
38
  | What's in client X's build repo docs? | `ia client-build <slug> [query]` |
38
39
  | Find a client's call transcript / Drive deliverable | `ia client-drive <slug> [query]` |
@@ -60,7 +61,12 @@ list, including this one.
60
61
  1Password vault immediately.
61
62
  - Anything touching existing files skips or refuses; nothing overwrites
62
63
  silently. The root `.env` is never overwritten, not even by
63
- `wizard --update`.
64
+ `wizard --update` or `sync --docs`.
65
+ - `ia env fill` covers the technician var set only. The infra/portal/payments
66
+ vars are withheld as a bare count, never listed by name — don't "helpfully"
67
+ re-add them to a report. `--admin` opts in for whoever holds that grant.
68
+ - Commands are single words. If a new one ever needs two, join them with a
69
+ colon (`family:verb`), never a dash.
64
70
  - Portal mutations and `client-intake` are deliberately CLI-only (no MCP
65
71
  twin) — don't script agents around that.
66
72
 
@@ -73,9 +79,16 @@ list, including this one.
73
79
  - No `ia` on PATH yet? The CLI lives in `team-tools/`:
74
80
  `pnpm install && pnpm -r build`, then `node apps/cli/dist/index.js …`
75
81
  (bootstrap order for a from-scratch machine is in root `ONBOARDING.md`).
76
- - Cloning InstallAgent repos requires GitHub SSH access; on shared machines
77
- the identity may be directory-scoped — if a clone fails with auth errors,
78
- say so rather than retrying with other credentials.
82
+ - Cloning InstallAgent repos works over **HTTPS** using the gh CLI's
83
+ credential helper, so `gh auth login` is sufficient; `ia wizard --ssh`
84
+ switches to SSH URLs. On shared machines the git identity may be
85
+ directory-scoped — if a clone fails with auth errors, say so rather than
86
+ retrying with other credentials.
87
+ - **Windows:** run `op`-touching commands (`ia env fill`, `ia env push`) from
88
+ PowerShell. 1Password supports PowerShell only, so its CLI cannot
89
+ authenticate from Git Bash — the command will look installed and still
90
+ fail. `ia doctor` detects this and adjusts its fix-it text; if you ever see
91
+ `brew` suggested on Windows, that is a bug to report, not to work around.
79
92
 
80
93
  ## When NOT to use ia
81
94
 
@@ -4,16 +4,23 @@ description: >-
4
4
  The official Install Agent brand kit for deliverables — the canonical palette
5
5
  (deep red #d11a1a on white / signal red #ff2d2d, white foreground), the official logo
6
6
  assets, and copy-paste recipes that apply them to Excalidraw diagrams (house
7
- RED theme) and client PDFs (SOW, proposal, overview, onboarding, one-pagers).
8
- Use this WHENEVER a diagram or document needs to look on-brand — triggers
9
- include "make it on-brand", "use our brand color/red", "add our logo",
10
- "official logo not a generic one", "branded PDF", "SOW/proposal PDF", "red
11
- excalidraw", "match our theme", or any client-facing visual. Reach for it even
12
- if the user never says "skill". It mirrors the single brand source
7
+ RED theme), client PDFs (SOW, proposal, overview, onboarding, one-pagers), and
8
+ **client decks / Google Slides presentations** (scripts/deck.py + a
9
+ duplicate-me assets/installagent-deck-template.pptx + scripts/deck_lint.py,
10
+ the gate that fails a deck on any off-brand colour, typeface, unresolvable
11
+ glyph or out-of-bounds shape and renders every slide so you can actually look
12
+ at it). Use this WHENEVER a diagram, document, deck or presentation needs to
13
+ look on-brand — triggers include "make it on-brand", "use our brand
14
+ color/red", "add our logo", "official logo not a generic one", "branded PDF",
15
+ "SOW/proposal PDF", "red excalidraw", "match our theme", "build a deck",
16
+ "client presentation", "Google Slides", "slide deck for the call", "deck
17
+ template", or any client-facing visual. Reach for it even if the user never
18
+ says "skill". It mirrors the single brand source
13
19
  (team-web/packages/ui/theme.css) and ships scripts/brand.py so generators
14
20
  never hard-code a hex or re-draw the logo. Pairs with client-workflow-diagram,
15
- engagement-spec, and contract-tech-agnostic — this one governs BRAND, those
16
- govern content/layout.
21
+ engagement-spec, tech-call-prep (the deck's content comes from the call
22
+ agenda), and contract-tech-agnostic — this one governs BRAND, those govern
23
+ content/layout.
17
24
  ---
18
25
 
19
26
  # Install Agent brand kit — branded diagrams & PDFs
@@ -47,10 +54,16 @@ generator imports one module and is automatically on-brand.
47
54
  |---|---|---|
48
55
  | **Branded Excalidraw** (red theme) | [`references/excalidraw-red-theme.md`](references/excalidraw-red-theme.md) | editable `.excalidraw` in the house red theme |
49
56
  | **Branded PDF** (SOW, proposal, overview, one-pager) | [`references/branded-pdf.md`](references/branded-pdf.md) | client PDF with the official logo + brand red |
57
+ | **Client deck / Google Slides** | [`references/deck-guide.md`](references/deck-guide.md) | `.pptx` that converts to native Slides on Drive upload |
50
58
 
51
- Both are driven by [`scripts/brand.py`](scripts/brand.py) — palette constants,
59
+ All are driven by [`scripts/brand.py`](scripts/brand.py) — palette constants,
52
60
  `logo_svg()`, an `Excalidraw` builder, and `pdf_css()` / `pdf_hero()` /
53
- `render_pdf()` for WeasyPrint.
61
+ `render_pdf()` for WeasyPrint. Decks add
62
+ [`scripts/deck.py`](scripts/deck.py) (builder),
63
+ [`scripts/deck_lint.py`](scripts/deck_lint.py) (the gate),
64
+ [`scripts/logo_raster.py`](scripts/logo_raster.py) (SVG → PNG, since pptx can't
65
+ embed SVG), and a duplicate-me template at
66
+ `assets/installagent-deck-template.pptx`.
54
67
 
55
68
  ## How to use it
56
69
 
@@ -73,6 +86,25 @@ numbers. Then `brand.render_pdf(body, out)` rasterizes via WeasyPrint. Content
73
86
  discipline stays with `engagement-spec` (overviews/onboarding) and
74
87
  `contract-tech-agnostic` (SOWs) — this skill only guarantees the brand.
75
88
 
89
+ ### Client deck (Google Slides)
90
+
91
+ Two paths, one gate — full detail in
92
+ [`references/deck-guide.md`](references/deck-guide.md).
93
+
94
+ - **By hand:** upload `assets/installagent-deck-template.pptx` to Drive (it
95
+ converts to native Slides), then **duplicate** the slide whose *shape* fits
96
+ your point and type over it. Its OOXML theme is branded, so a text box added
97
+ by hand inherits Hanken Grotesk and deep red rather than Calibri and Office
98
+ blue. Delete the read-me slide and every unused archetype before sharing.
99
+ - **In code:** `from deck import Deck` and compose the archetypes — `cover`,
100
+ `pipeline`, `ladder`, `cards`, `flow` (struck-out cut step), `gantt`,
101
+ `tiles`, `decisions`, `chat`, `kanban`, plus `table` / `callout` /
102
+ `question_band` / `panel`. A deck is ~80 lines of content and no geometry.
103
+
104
+ **A deck is presented, not read.** Every slide carries a picture of the idea
105
+ and only the words that anchor it; prose belongs in the speaker's mouth or in
106
+ `docs/05-call-agenda.md`. The linter warns past 180 words on a slide.
107
+
76
108
  ### Verify before shipping
77
109
 
78
110
  - Excalidraw: `python -m json.tool file.excalidraw` parses; opens at
@@ -80,6 +112,15 @@ discipline stays with `engagement-spec` (overviews/onboarding) and
80
112
  - PDF: render pages to PNG (`pdftoppm -png -r 110 out.pdf page`) and eyeball —
81
113
  the official logo renders, the accent is brand red (not a stray blue), nothing
82
114
  spills onto a near-empty page.
115
+ - Deck: `python scripts/deck_lint.py mydeck.pptx --render`. It reads the raw
116
+ OOXML (off-brand hex, off-brand typeface, hard line breaks, unresolvable
117
+ glyphs, out-of-bounds shapes, invisible hairlines, wrong slide size) **and**
118
+ renders every slide to PNG so you can actually look at it. `--render` is the
119
+ step people skip: there is no LibreOffice on most of our machines, so Quick
120
+ Look via `qlmanage` is the only local preview — and it only ever previews
121
+ slide 1, which is why the linter splits the deck one slide per file first.
122
+ Geometry checks pass on decks with eight visible defects; looking is not
123
+ optional.
83
124
 
84
125
  ## Quality rules
85
126
 
@@ -109,4 +150,12 @@ images. The logo assets here are copies of
109
150
  - [ ] Official logo used (PDF hero + running header); no generic glyph.
110
151
  - [ ] Generator imports `scripts/brand.py` — no hard-coded hexes.
111
152
  - [ ] Excalidraw validates / opens; PDF previewed as PNG.
153
+ - [ ] Deck: `deck_lint.py --render` clean **and every slide looked at** — a
154
+ clean geometry pass is not a clean deck.
155
+ - [ ] Deck: white surfaces, not the dark marketing palette; the logo is the
156
+ official asset (lockup on the cover, mark on every other slide).
112
157
  - [ ] No secrets or customer data in labels; branding says Install Agent.
158
+ - [ ] **Not this skill's job, but check it anyway:** every number and status
159
+ word on a deliverable traces to a source file. The linter cannot tell
160
+ "passing 25/25" from an unrun test set — see `deck-guide.md` § mistakes
161
+ 12–15 for the four that reached a draft.
@@ -0,0 +1,181 @@
1
+ # Client decks — the template, the builder, and the mistakes not to repeat
2
+
3
+ Two paths to an on-brand deck. Both end in the same linter.
4
+
5
+ | You are… | Use | Then |
6
+ |---|---|---|
7
+ | Writing a deck by hand | `assets/installagent-deck-template.pptx` | Upload to Drive → it converts to native Google Slides → duplicate the slide whose *shape* fits your point |
8
+ | Generating a deck in code | `scripts/deck.py` | `python scripts/deck_lint.py yourdeck.pptx --render` before you hand it over |
9
+
10
+ Both are generated from `scripts/brand.py`, which mirrors the single brand
11
+ source (`team-web/packages/ui/theme.css`). **Nothing here contains a hex
12
+ literal, and neither should your deck script.**
13
+
14
+ ---
15
+
16
+ ## The hand-built path
17
+
18
+ 1. Upload `assets/installagent-deck-template.pptx` to the client's Drive
19
+ folder — or to your own and copy it. Drive converts `.pptx` to native
20
+ Slides on upload, keeping the layout.
21
+ 2. Slide 2 is the read-me. Read it, then delete it before sharing.
22
+ 3. **Duplicate, don't create.** Right-click a slide → Duplicate, then type over
23
+ it. A slide you add from scratch loses the type stack and the spacing.
24
+ 4. Delete every archetype you didn't use. A ten-slide template is not a
25
+ ten-slide deck.
26
+ 5. Fix the footer date and the `n/N` page numbers — they are text, not fields.
27
+
28
+ The file's **OOXML theme** is patched too, so Slides reports the theme as
29
+ "Install Agent" and a text box you add by hand inherits Hanken Grotesk and
30
+ deep red instead of Calibri and Office blue.
31
+
32
+ ---
33
+
34
+ ## The generated path
35
+
36
+ ```python
37
+ import sys
38
+ sys.path.append("/Users/…/skills/installagent-brand-kit/scripts")
39
+ from deck import Deck, RED, RED_SIG, MUTED
40
+
41
+ d = Deck(client="Acme Co", date="14 Sep 2026", total=4)
42
+
43
+ d.cover("ACME CO", "Where we are, and what we need to decide today",
44
+ "Attendees 14 September 2026 · 60 minutes",
45
+ outcomes=[("A priority order", "we all agree on"),
46
+ ("A timeline", "you can plan against"),
47
+ ("A short list", "of what we need from you")])
48
+
49
+ s = d.slide("01 · already working", "One thing is live",
50
+ "And it has been for two weeks.")
51
+ d.pipeline(s, [("inbox", "Mail arrives", "Any hour"),
52
+ ("read", "Classified", "Understood, not matched"),
53
+ ("file", "Filed", "Your own labels"),
54
+ ("act", "Archived", "By itself")], accent=3)
55
+ d.callout(s, "The sentence you want repeated back to you.", "One clause more.")
56
+
57
+ s = d.slide("02 · what we need", "From your side",
58
+ "None of this is engineering time.")
59
+ d.tiles(s, [("⚠", "The blocker", "What it unlocks.", "OWNER — VERB", True),
60
+ ("→", "A question", "Asked, not answered.", "OWNER", False)], cols=4)
61
+
62
+ s = d.slide("03 · next steps", "The next seven days")
63
+ d.kanban(s, [("TODAY", RED, [(1, "Thing", "US", False)]),
64
+ ("THIS WEEK", RED_SIG, [(2, "Their thing", "THEM", True)]),
65
+ ("LATER", MUTED, [(3, "Dated thing", "US", False)])])
66
+
67
+ d.save("acme-deck.pptx")
68
+ ```
69
+
70
+ **Archetypes** (all take the `Slide` returned by `d.slide()` and advance its
71
+ cursor, so you can stack two on one page):
72
+
73
+ `cover` · `pipeline` · `ladder` · `cards` · `flow` (with a struck-out cut step)
74
+ · `gantt` · `tiles` · `decisions` · `chat` · `kanban` · plus `table`,
75
+ `callout`, `question_band`, `panel`, `stat`.
76
+
77
+ For a bespoke diagram — a map, a topology — use `panel()` for the left-hand
78
+ narrative card; it returns the x where the free area starts. Draw into that
79
+ area with the primitives (`card`, `bar`, `badge`, `pill`, `arrow`, `rule`) so
80
+ the diagram stays on-palette.
81
+
82
+ `d.save()` refuses to write if the slide count doesn't match `total=` — the
83
+ footer page numbers would otherwise lie.
84
+
85
+ ---
86
+
87
+ ## The mistakes this exists to prevent
88
+
89
+ Every one of these reached a draft. Ordered by how badly it would have landed.
90
+
91
+ ### Brand
92
+
93
+ 1. **Building a client deck on the marketing site's dark palette.** The site is
94
+ always-dark; **documents live on white with `#d11a1a`**. `brand-tokens.md`
95
+ is explicit: the dark `theme.css` neutrals are *"for the always-dark
96
+ marketing site — do not use them for client PDFs or diagrams."*
97
+ 2. **Introducing a second hue for semantics** — blue "client" pins, amber
98
+ "stale" markers. **Red is the only hue.** Meaning rides on glyphs
99
+ (`✓ → ⚠ ✕`), fill weight, and dashed-vs-solid outlines. `deck_lint.py`
100
+ fails the build on any hex not in `brand.py`.
101
+ 3. **Using signal red `#ff2d2d` as decoration.** It means attention. Deep red
102
+ `#d11a1a` is the primary; if everything is bright red, nothing is urgent.
103
+ 4. **Re-creating the logo**, or screenshotting it. `logo_raster.py` rasterises
104
+ the official SVGs — full lockup on the cover, icon mark in every running
105
+ header. `deck_lint.py` fails a slide with no logo at all.
106
+
107
+ ### Rendering — things that look fine locally and break on the projector
108
+
109
+ 5. **1px rules.** A `GRID`-coloured shape 9525 EMU thick is invisible
110
+ projected. The gantt gridlines shipped this way. Floor is **12700 EMU**;
111
+ `deck.HAIRLINE` is that value.
112
+ 6. **Glyphs that don't resolve.** `▮`/`▯` rendered as tiny boxes and a missing
113
+ glyph. Draw swatch shapes instead. The linter has a denylist; `✓ → ⚠ ✕ ● ★
114
+ ◌` are safe.
115
+ 7. **`\n` inside a run.** Renderers disagree on whether it breaks. `deck.py`
116
+ strips it; add a second paragraph, or let `word_wrap` do the work.
117
+ 8. **`Inches(13.333)` for a 16:9 width.** That is 12191695 EMU — 305 short of
118
+ true 16:9 against 7.5in, so Slides rescales on import. Use
119
+ `Emu(12192000)`, which `deck.py` does.
120
+ 9. **Text frames overhanging the footer.** `deck.tb()` clamps every frame to
121
+ `BOTTOM_SAFE`; the linter fails on any shape past the slide edge.
122
+ 10. **A "radius" stretched into an ellipse.** If your diagram's coordinate
123
+ space isn't square, a circle sized in *units* comes out oval. Size radial
124
+ things in **inches**, not canvas units.
125
+ 11. **Labels colliding with the thing they label.** Only visible by looking.
126
+
127
+ ### Content — not enforceable, but the expensive kind
128
+
129
+ 12. **An unrun test quoted as a passing score.** A `25/25` reached a
130
+ client-facing slide while the workplan said the set had *"not yet [been]
131
+ run."* Every number on a slide needs a source file; if there is no
132
+ evidence file, say what you actually have.
133
+ 13. **A status word doing more work than the repo supports.** "Finished",
134
+ "the only thing left", "it tracks his edits" — each was one phase ahead of
135
+ reality. Grep the workplan before you write a status word.
136
+ 14. **A claim that undercuts your own ask.** "Carries no patient data" two
137
+ slides before asking them to sign a data-handling agreement.
138
+ 15. **Contradicting a stakeholder who will be in the room.** A slide said
139
+ "read-only" about a tool whose owner had explicitly required it be
140
+ editable. Read the last call's notes before you write the roadmap slide.
141
+
142
+ The linter cannot catch 12–15. The client repo's `CADENCE.md` § surface matrix
143
+ is the process that does: every claim traces to `docs/`, and `docs/` traces to
144
+ a call note.
145
+
146
+ ---
147
+
148
+ ## Verifying a deck before you send it
149
+
150
+ ```bash
151
+ python scripts/deck_lint.py mydeck.pptx --render
152
+ ```
153
+
154
+ Errors block; warnings are advisory (word count over 180, hairlines).
155
+
156
+ **`--render` is the step people skip and shouldn't.** There is no LibreOffice
157
+ on most of our machines, so the only local way to *see* a `.pptx` is macOS
158
+ Quick Look — and `qlmanage` previews only slide 1. The linter works around that
159
+ by splitting the deck into one file per slide and rendering each. It is the
160
+ only check that catches composition: collisions, dead whitespace, a shape
161
+ covering half the page. On the deck this guide came from, geometry was clean
162
+ and **eight defects were still visible**.
163
+
164
+ Then: upload to Drive, and confirm after conversion that Hanken Grotesk and
165
+ JetBrains Mono resolved (both are Google Fonts and normally do) and that any
166
+ hand-drawn diagram survived.
167
+
168
+ ---
169
+
170
+ ## Regenerating the template
171
+
172
+ After any change to `theme.css`, `brand.py`, or `deck.py`:
173
+
174
+ ```bash
175
+ cd scripts
176
+ python make_deck_template.py
177
+ python deck_lint.py ../assets/installagent-deck-template.pptx --render
178
+ ```
179
+
180
+ Never hand-edit the `.pptx` in `assets/` — it is a build artifact, and a manual
181
+ edit is how it drifts from the brand source.