@installagent/sdk 0.1.0 → 0.3.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 (114) hide show
  1. package/dist/agent-mirror.d.ts +69 -0
  2. package/dist/agent-mirror.js +275 -0
  3. package/dist/agent-templates.d.ts +36 -2
  4. package/dist/agent-templates.js +173 -3
  5. package/dist/claude-hours.d.ts +118 -0
  6. package/dist/claude-hours.js +523 -0
  7. package/dist/client-drive.d.ts +3 -0
  8. package/dist/client-drive.js +2 -2
  9. package/dist/client-linear-create.d.ts +26 -0
  10. package/dist/client-linear-create.js +46 -0
  11. package/dist/client-linear.d.ts +28 -9
  12. package/dist/client-linear.js +36 -14
  13. package/dist/docs-search.d.ts +19 -6
  14. package/dist/docs-search.js +32 -11
  15. package/dist/doctor.d.ts +9 -0
  16. package/dist/doctor.js +126 -23
  17. package/dist/env-fill.d.ts +13 -0
  18. package/dist/env-fill.js +55 -13
  19. package/dist/env-push.d.ts +3 -0
  20. package/dist/env-push.js +11 -6
  21. package/dist/env-registry.d.ts +29 -0
  22. package/dist/env-registry.js +123 -9
  23. package/dist/exec.js +15 -2
  24. package/dist/git.d.ts +31 -0
  25. package/dist/git.js +59 -0
  26. package/dist/google-service-account.d.ts +20 -0
  27. package/dist/google-service-account.js +49 -0
  28. package/dist/hours-estimate.d.ts +43 -0
  29. package/dist/hours-estimate.js +159 -0
  30. package/dist/hours-export-schedule.d.ts +35 -0
  31. package/dist/hours-export-schedule.js +188 -0
  32. package/dist/hours-ledger.d.ts +129 -0
  33. package/dist/hours-ledger.js +882 -0
  34. package/dist/index.d.ts +25 -6
  35. package/dist/index.js +25 -6
  36. package/dist/linear-project.d.ts +2 -2
  37. package/dist/linear-project.js +2 -2
  38. package/dist/log.d.ts +28 -0
  39. package/dist/log.js +73 -0
  40. package/dist/n8n-executions.d.ts +85 -0
  41. package/dist/n8n-executions.js +259 -0
  42. package/dist/op-cli.d.ts +29 -0
  43. package/dist/op-cli.js +52 -0
  44. package/dist/platform.d.ts +35 -0
  45. package/dist/platform.js +39 -0
  46. package/dist/portal-admin.d.ts +108 -0
  47. package/dist/portal-admin.js +94 -1
  48. package/dist/standup.d.ts +88 -0
  49. package/dist/standup.js +235 -0
  50. package/dist/sync-repos.d.ts +54 -0
  51. package/dist/sync-repos.js +89 -0
  52. package/dist/template-sync.d.ts +11 -0
  53. package/dist/template-sync.js +16 -0
  54. package/dist/triage-backfill.d.ts +37 -0
  55. package/dist/triage-backfill.js +211 -0
  56. package/dist/triage-enable.d.ts +90 -0
  57. package/dist/triage-enable.js +428 -0
  58. package/dist/triage-gates.d.ts +252 -0
  59. package/dist/triage-gates.js +951 -0
  60. package/dist/wizard.d.ts +15 -0
  61. package/dist/wizard.js +35 -56
  62. package/dist/workspace-docs.d.ts +44 -0
  63. package/dist/workspace-docs.js +73 -0
  64. package/dist/workspace-push.d.ts +39 -0
  65. package/dist/workspace-push.js +78 -0
  66. package/dist/workspace-status.d.ts +37 -0
  67. package/dist/workspace-status.js +114 -0
  68. package/package.json +2 -2
  69. package/templates/env.example +37 -23
  70. package/templates/workspace-root/.claude/settings.json +12 -1
  71. package/templates/workspace-root/AGENT.md +7 -5
  72. package/templates/workspace-root/ONBOARDING.md +65 -8
  73. package/templates/workspace-root/skills/.github/workflows/pr-to-slack.yml +127 -0
  74. package/templates/workspace-root/skills/CLAUDE.md +29 -6
  75. package/templates/workspace-root/skills/README.md +171 -0
  76. package/templates/workspace-root/skills/ad-machine/SKILL.md +140 -0
  77. package/templates/workspace-root/skills/backtest-acceptance-gates/SKILL.md +293 -0
  78. package/templates/workspace-root/skills/backtest-acceptance-gates/backtest-acceptance-gates-guide.pdf +0 -0
  79. package/templates/workspace-root/skills/backtest-acceptance-gates/references/evidence-record-template.md +128 -0
  80. package/templates/workspace-root/skills/backtest-acceptance-gates/references/harness-checklist.md +90 -0
  81. package/templates/workspace-root/skills/client-deliverables/SKILL.md +1 -1
  82. package/templates/workspace-root/skills/client-deliverables/references/package-layout.md +3 -2
  83. package/templates/workspace-root/skills/client-latest/SKILL.md +343 -0
  84. package/templates/workspace-root/skills/client-latest/catchup.command.md +18 -0
  85. package/templates/workspace-root/skills/cloud-devops/SKILL.md +235 -0
  86. package/templates/workspace-root/skills/email-triage-rollout/SKILL.md +258 -0
  87. package/templates/workspace-root/skills/engagement-spec/SKILL.md +51 -18
  88. package/templates/workspace-root/skills/engagement-spec/references/spec-templates.md +10 -4
  89. package/templates/workspace-root/skills/gcloud-cli-setup/SKILL.md +100 -0
  90. package/templates/workspace-root/skills/github-profile/SKILL.md +106 -0
  91. package/templates/workspace-root/skills/google-chat-app-setup/SKILL.md +136 -0
  92. package/templates/workspace-root/skills/google-chat-app-setup/google-chat-app-setup-guide.pdf +0 -0
  93. package/templates/workspace-root/skills/house-voice/SKILL.md +80 -4
  94. package/templates/workspace-root/skills/ia-cli/SKILL.md +49 -7
  95. package/templates/workspace-root/skills/init_repo/SKILL.md +188 -0
  96. package/templates/workspace-root/skills/installagent-brand-kit/SKILL.md +59 -10
  97. package/templates/workspace-root/skills/installagent-brand-kit/assets/installagent-deck-template.pptx +0 -0
  98. package/templates/workspace-root/skills/installagent-brand-kit/references/deck-guide.md +181 -0
  99. package/templates/workspace-root/skills/installagent-brand-kit/scripts/deck.py +652 -0
  100. package/templates/workspace-root/skills/installagent-brand-kit/scripts/deck_lint.py +201 -0
  101. package/templates/workspace-root/skills/installagent-brand-kit/scripts/logo_raster.py +102 -0
  102. package/templates/workspace-root/skills/installagent-brand-kit/scripts/make_deck_template.py +290 -0
  103. package/templates/workspace-root/skills/salesforce-api-snapshot/SKILL.md +379 -0
  104. package/templates/workspace-root/skills/salesforce-api-snapshot/references/schema-discovery-soql.md +153 -0
  105. package/templates/workspace-root/skills/salesforce-api-snapshot/references/snapshot-storage.md +122 -0
  106. package/templates/workspace-root/skills/salesforce-api-snapshot/salesforce-api-snapshot-guide.pdf +0 -0
  107. package/templates/workspace-root/skills/slack-voice/SKILL.md +158 -0
  108. package/templates/workspace-root/skills/sso-gated-client-app/SKILL.md +337 -0
  109. package/templates/workspace-root/skills/sso-gated-client-app/sso-gated-client-app-guide.pdf +0 -0
  110. package/templates/workspace-root/skills/tech-call-prep/SKILL.md +146 -47
  111. package/templates/workspace-root/skills/vendor-feed-ingestion/SKILL.md +323 -0
  112. package/templates/workspace-root/skills/vendor-feed-ingestion/references/delivery-contract-template.md +110 -0
  113. package/templates/workspace-root/skills/vendor-feed-ingestion/references/feed-guards.md +134 -0
  114. package/templates/workspace-root/skills/vendor-feed-ingestion/vendor-feed-ingestion-guide.pdf +0 -0
@@ -0,0 +1,258 @@
1
+ ---
2
+ name: email-triage-rollout
3
+ description: >-
4
+ Roll out an AI email-triage assistant into a client's live mailbox as a
5
+ staged program instead of a one-shot deploy — soak (watch, write nothing),
6
+ label-only, organize (noise leaves the inbox), then full (drafts). Covers the
7
+ one thing that makes it a product rather than a build: the exit gate each
8
+ stage must pass before the next one starts, with real numbers and a
9
+ zero-tolerance list, so a technician cannot promote on a hunch. Also covers
10
+ the week-1 soak report (the fixed table set that turns a week of observed
11
+ mail into a taxonomy the client approves), what to say to the client at each
12
+ promotion, the pause switch, and how each promotion lands as one CADENCE
13
+ slice in the client's build repo. Use this WHENEVER an engagement involves
14
+ email triage, inbox cleanup, auto-labeling, or mailbox organization — "set up
15
+ their inbox", "triage their email", "the AI is labeling wrong", "can we turn
16
+ on archiving yet", "week 1 of the email agent", "what stage are they on",
17
+ "write the soak report", "is it safe to enable drafts" — or when deploying
18
+ the `email-gmail-triage` or `email-outlook-triage` banked template. Reach for
19
+ it even if the user never says "skill". It governs the ROLLOUT; each
20
+ template's own `sop.md` in the agents/ bank carries the per-provider detail.
21
+ ---
22
+
23
+ # Email triage rollout
24
+
25
+ ## What this is for
26
+
27
+ An email triage agent is the highest-trust automation we deploy. It has write
28
+ access to the one system a business owner checks a hundred times a day, and the
29
+ failure mode is not an error message — it is an email that was there and now is
30
+ not. One misfiled message costs more trust than three weeks of correct
31
+ labelling earns.
32
+
33
+ So we never deploy it at full power. It goes in as **four stages**, each one
34
+ selected by a single config value and each gated on evidence from the client's
35
+ own mail.
36
+
37
+ **The stage model, in one line each:**
38
+
39
+ | Stage | Value | What changes in the mailbox |
40
+ |---|---|---|
41
+ | 1. Soak | `soak` | **Nothing.** It classifies and records, and writes nothing at all |
42
+ | 2. Label only | `label` | Labels/categories appear. Nothing leaves the inbox |
43
+ | 3. Organize | `organize` | Newsletters and noise leave the inbox, always tagged first |
44
+ | 4. Full | `full` | Reply drafts appear in Drafts. Still never sends, never deletes |
45
+
46
+ **There is no calendar.** A stage ends when its gate passes, not on a Monday.
47
+ A busy inbox can reach stage 4 in ten days; a quiet one takes a month, and
48
+ that is correct — the gates need mail to measure.
49
+
50
+ **But the client heard "four weeks".** The kickoff deck (`docs/
51
+ kickoff-presentation.html`, slide 3) shows watch → report → diagrams → first
52
+ build live as four weeks. That is how we set expectations, said out loud as
53
+ the *typical shape* with one hedge ("each step moves when its check passes,
54
+ not on a date"). The gates are the contract. When a gate lags the deck, tell
55
+ the client the number and the likely day — never let the date slip silently.
56
+
57
+ **The client-facing vocabulary is four lanes** — **Critical / Today / Later /
58
+ Noise** — on the deck, in the soak report, and in every Slack message they
59
+ read. The templates' internal dispositions and categories map onto them (the
60
+ table is in each `sop.md` § *Client-facing lanes*; the code is
61
+ `team-tools` `triage-gates.ts`). Never say `archive` or `SalesPitch` to a
62
+ client.
63
+
64
+ ## Start here
65
+
66
+ 1. **Identify the template.** Gmail → `agents/email-gmail-triage/`. Outlook or
67
+ 365 → `agents/email-outlook-triage/`. Never build inbox triage from a blank
68
+ canvas.
69
+ 2. **Read that template's `sop.md`.** It is the authority for preconditions,
70
+ the stage table, the gate numbers, and rollback. This skill is the shared
71
+ method; the SOP is the provider-specific contract.
72
+ 3. **Set up the record before the first publish.** The classification record
73
+ is the client portal's `triage_classifications` table — one row per
74
+ message, sender domain only — written by the template's record branch
75
+ (`🧺 Batch Record Rows` → `📊 Record to Portal`). There is no sheet to
76
+ create. Register the org + agent (`ia portal create-agent`), bind the two
77
+ credentials in the n8n UI (`IA - portal - agent-ingest`,
78
+ `IA - slack - agent-zero`), then **`ia triage enable <slug>`** — it checks
79
+ the live workflow's record wiring, marks the agent as a triage agent, and
80
+ prints the next steps. Publish only after it passes, then check the first
81
+ execution's `📊 Record to Portal` output (never the `⚙️ Stage` or trigger
82
+ nodes — they hold full email bodies).
83
+ 4. **Confirm which stage the client is on.** It is not a memory question — the
84
+ `stage` column in the client's classification record, and the `stage=`
85
+ field in the n8n execution log, both answer it.
86
+ 5. **Read the client repo's `CADENCE.md`.** Every promotion is one cadence
87
+ slice, and the surface matrix says what must move in the same commit.
88
+
89
+ ## The two rules that carry the whole program
90
+
91
+ **1. Promotion is config, never node surgery.** One value (`TRIAGE_STAGE` in
92
+ the `⚙️ Stage` node), published, re-exported, committed. Never enable a
93
+ disabled node to promote a client. A disabled node leaves no audit trail and
94
+ cannot answer "what stage is this client on?".
95
+
96
+ **2. A gate is a number plus a zero-tolerance list.** "It looks good" is not a
97
+ gate. Neither is a percentage on its own — 95% correct still permits the one
98
+ error that ends the engagement. Every gate names the errors that are never
99
+ acceptable at any percentage.
100
+
101
+ ## The soak report
102
+
103
+ Week 1's deliverable is not a working workflow — it is a **taxonomy the client
104
+ approves**. Every soak report uses the same tables, so a technician reading
105
+ their second one already knows the shape.
106
+
107
+ Write it to `evidence/YYYY-MM-DD-email-triage-soak-report.md` in the client's
108
+ build repo, from the classification record — **with the tool, not by
109
+ hand**:
110
+
111
+ ```
112
+ ia triage soak-report <slug> # reads the portal record
113
+ ia triage soak-report <slug> --since 2026-10-01T00:00Z # only rows from this instant on
114
+ ia triage soak-report <slug> --lane "Permits=Today" # a client-added category
115
+ ```
116
+
117
+ It writes every table below in the fixed order, pre-computes the two numeric
118
+ gate-A checks, adds the lane view (table 3b), and refuses to overwrite a file
119
+ already written today (`--force`). You fill table 6's one-line definitions and
120
+ table 7's answers, then send. Needs `IA_PORTAL_ADMIN_SECRET` on your machine
121
+ (`ia env fill`); the evidence header names the source it read. (A client from
122
+ before the portal move still reads its old sheet — see the `ia-cli` skill's
123
+ source rule.)
124
+
125
+ **Required tables:**
126
+
127
+ 1. **Volume** — total messages, messages/day, busiest and quietest day. Sets
128
+ the expectation for how fast the later gates can pass.
129
+ 2. **Sender domains** — top 20 by volume, with a share-of-total column, and a
130
+ count of the long tail below them. This is where the taxonomy comes from.
131
+ A domain with 40 messages and no home in the proposed labels is a missing
132
+ category.
133
+ 3. **Proposed disposition/category mix** — what the classifier said, as counts
134
+ and shares. Read it as a hypothesis, not a result. **3b. Client-facing
135
+ lanes** — the same mail as Critical / Today / Later / Noise; this is the
136
+ table the client sees first.
137
+ 4. **Review-lane rate** — the share the model was not confident about. Above
138
+ ~20% at soak means the taxonomy does not fit the mail yet. Fix that before
139
+ stage 2, not by lowering the confidence floor.
140
+ 5. **Action-lane load** — how many messages/day would be starred or flagged.
141
+ If it is most of the inbox, the automation gives the owner nothing. This
142
+ number is the one clients feel most directly.
143
+ 6. **Proposed taxonomy** — the label/category list, each with a one-line
144
+ definition and its expected volume from table 2. This is the thing the
145
+ client says yes or no to.
146
+ 7. **Open questions** — anything the mail could not settle. Sender roster
147
+ gaps, ambiguous categories, mail whose importance depends on business
148
+ context we do not have.
149
+
150
+ **Then ask the client to approve or change the list, and wait for the answer.**
151
+ It is their mailbox and their vocabulary. A taxonomy we chose alone is a
152
+ taxonomy they will not use, and the gate does not pass without their yes in
153
+ writing.
154
+
155
+ ## Sampling for the precision gates
156
+
157
+ ```
158
+ ia triage sample <slug> --stage label # gate B → evidence/<date>-email-triage-stage2-gate.md
159
+ ia triage sample <slug> --stage organize # gate C → evidence/<date>-email-triage-stage3-gate.md
160
+ ```
161
+
162
+ The tool draws the sample, computes the review-lane rate over the stage
163
+ window, and writes the judging table with the thresholds and the
164
+ zero-tolerance list pre-filled. It cannot pass or fail the gate — **you open
165
+ every `message_id` and judge**. The building technician judges their own gate
166
+ (decided 2026-09-16); the seed printed in the evidence header lets anyone
167
+ re-draw the identical sample later, which is the check on that call.
168
+
169
+ - **Sample at random across the whole window**, not the most recent N. Recent
170
+ mail is the mail the technician has been staring at all week. The tool does
171
+ this; a spreadsheet sort does not.
172
+ - **Sample size 50** unless the SOP says otherwise. Open each message by its
173
+ `message_id` in the client's own mailbox — that is where the content is
174
+ allowed to live; it never gets copied into the record or the evidence
175
+ file.
176
+ - **A gate can only be sampled from rows written at the current stage.** After
177
+ a promotion the behaviour changed, so earlier rows are a different
178
+ experiment. `--since <promotion instant>` makes that exact, instead of
179
+ trusting the `stage` column alone.
180
+ - **Judge against what the owner would have wanted**, not against what the
181
+ prompt says. The prompt is the thing under test.
182
+
183
+ ## What to tell the client
184
+
185
+ Use the `house-voice` skill — the Slack register.
186
+
187
+ - **Before stage 1:** what it reads, that it changes nothing yet, and roughly
188
+ how long. Get the yes.
189
+ - **At the taxonomy gate:** the soak findings in plain language plus the
190
+ proposed list. This is the one place we wait for a reply.
191
+ - **At every promotion:** what changes today, and how they undo it.
192
+ - **When a gate fails:** say so, with the number and what you are changing. A
193
+ client who hears "82%, so I am not moving it forward yet" trusts the next
194
+ promotion. A silent promotion is how a client finds out by noticing a moved
195
+ email — and that conversation costs more than the message you skipped.
196
+
197
+ ## Landing a promotion in the client repo
198
+
199
+ One CADENCE slice, one commit:
200
+
201
+ - `evidence/YYYY-MM-DD-email-triage-stageN-gate.md` — the sample, the counts,
202
+ every miss, the verdict.
203
+ - `docs/02-tech-spec.md` — the stage section.
204
+ - `docs/00-delivery-log.md` — an entry, since something shipped.
205
+ - `onboarding.html` — the Workflows status badge.
206
+ - `workflows/*.json` — re-exported from n8n in the same session.
207
+ - The Linear issue → Done, and the next stage's issue unblocked.
208
+
209
+ Track the four stages as a Linear sub-issue tree with `blockedBy` chains (see
210
+ the `linear` skill), so stage 3 cannot open before stage 2 closes. The chain
211
+ is the enforcement; a checklist in a doc is not.
212
+
213
+ ## Traps
214
+
215
+ - **A live client on an older version is not automatically retro-fitted.**
216
+ Record the exception in that repo's `AGENT.md` § *Client-specific gotchas*
217
+ and leave the running workflow alone until the next change touches it. That
218
+ includes a client that still records to a Google Sheet: moving it to the
219
+ portal follows the Gmail SOP § *Retro-fit* (double write for 7 days, the
220
+ backfill re-run says 0 new, then the Sheets node goes), one client per
221
+ session.
222
+ Re-cutting a production inbox to tidy up our own consistency is a risk the
223
+ client did not ask for.
224
+ - **The record is the health signal.** No new rows today means the workflow
225
+ is off, the trigger broke, or a credential expired. Nothing in the mailbox
226
+ will tell you — a triage agent that has stopped looks exactly like a quiet
227
+ inbox. The **portal's daily watch** (13:00 UTC) checks every active triage
228
+ agent and alerts `#team-techs` after 24 hours with no row; `ia triage
229
+ health <slug>` is the same check by hand (exit 1 when quiet). The portal
230
+ agent IS the registration — a client that never ran `ia triage enable` has
231
+ no watcher.
232
+ - **A record POST that fails alerts `#team-techs`** with the execution id.
233
+ Recovery: copy that execution's `🧺 Batch Record Rows` output into a file,
234
+ then `ia triage backfill <slug> --rows <file>` (idempotent; it refuses rows
235
+ from a workflow no agent of that client runs). The triage itself never
236
+ waited on the record, so no mail was missed.
237
+ - **The weekly client summary is automatic.** The `Team - Email Triage Weekly
238
+ Digest` workflow on our n8n reads the portal's totals
239
+ (`/api/triage-summary`) and posts, as Agent Zero, a short plain-words
240
+ summary into the client's channel every week (messages sorted, lane split,
241
+ current stage). That is the "weekly summary" the deck promises. It covers a
242
+ client only once its org has a channel: `ia portal set-org-slack-channel`.
243
+ Do not hand-write one; do read it, because a rising review lane there is
244
+ taxonomy drift.
245
+ - **Don't fix a bad taxonomy by lowering the confidence floor.** A rising
246
+ review lane is the system reporting that the categories do not match the
247
+ mail. Lowering the floor converts a visible problem into a silent one.
248
+ - **A failed execution must never silently drop a message.** Both mail
249
+ triggers advance by date, so a message whose run errored is never re-polled:
250
+ not retried, not labelled, and nothing says so. Every enabled write node
251
+ carries `retryOnFail`. If you add a node that writes to the mailbox, it
252
+ needs the same posture.
253
+ - **`soak` is also the pause switch.** Something looks wrong mid-engagement:
254
+ set the stage back to `soak` and publish. Writes stop, recording continues,
255
+ so the data does not stop while you diagnose.
256
+ - **The first reply draft the owner sees must not already be in their Drafts
257
+ folder.** Generate samples in a test run at the previous stage and paste
258
+ them into the channel.
@@ -43,7 +43,7 @@ you keep that same build folder's `onboarding.html` in sync:
43
43
  | `01-overview.md` | The client | Plain English, **tech-agnostic** | What we're solving, what we're building, what to expect. The doc you'd send them. |
44
44
  | `02-tech-spec.md` | Install Agent engineering | Precise, **names tools** | The implementation: architecture, data shapes, node-by-node, error handling, open questions. This is `onboarding.html`'s source of truth per `client-template/AGENT.md` — if they disagree, fix the page. |
45
45
  | `03-client-onboarding.md` | The client's admin/bookkeeper | Plain English, checklist | Access + decisions + info we need, split by "before kickoff" vs "during week 1". This is the **ask**. |
46
- | `04-access-checklist.md` | Install Agent (internal) | Terse status table | Same items as `03`, plus a Status column (HAVE/REQUESTED/MISSING) — the fast answer to "what are we still waiting on?" This is the **tracker**, kept current as access lands. Mirror it into `onboarding.html`'s Client tab. |
46
+ | `04-access-checklist.md` | Install Agent (internal) | Two terse status tables | §1 **credentials & grants** — one row per *system* we need a login, OAuth scope, share or API key for (every software named on the sales call); §2 **decisions & information owed** — never mixed in. Status HAVE/REQUESTED/MISSING. This is the **tracker**, kept current as access lands. Mirror §1 only into `onboarding.html`'s Access tab. |
47
47
  | `onboarding.html` | A technician landing on the build cold | Scannable, tab per topic | Every `REPLACE_WITH_*` token filled from the same source material as `01`–`04` (step 6) — so the tech discovery call happens with real context already on screen, not a blank template. |
48
48
 
49
49
  Look at the canonical exemplars before writing — match their depth and
@@ -161,35 +161,56 @@ The checklist that unblocks the build. Split by urgency so the client isn't
161
161
  overwhelmed:
162
162
 
163
163
  - **§1 Access (before kickoff)** — accounts/credentials we need, each with the
164
- *minimum* role and how they grant it (OAuth, invite). State that credentials
165
- go into *their* vault and we never take a password.
164
+ *minimum* role and how they grant it: OAuth/invite where the system
165
+ supports it, or their **portal's Access tab** for a straight login
166
+ (username/password, plus a two-factor setup key if that login uses 2FA) —
167
+ submitted directly, on their own time, into a 1Password vault dedicated to
168
+ their engagement. Reserve a scheduled working session for what the form
169
+ can't cover (an admin-consent flow they have to click through themselves).
166
170
  - **§2 Decisions (before kickoff)** — the choices only they can make (e.g.
167
171
  confidence threshold, point of contact).
168
172
  - **§3 Information (week 1, not blocking)** — exports, lists, edge cases to seed
169
173
  rules.
170
174
  - **§4 Ongoing** — review cadence, their time commitment, who owns what.
171
- - **§5 What we are NOT asking for** — explicitly. Builds trust, prevents the
172
- "why do you need my bank password" panic. (We never do.)
175
+ - **§5 What we are NOT asking for** — explicitly: nothing over Slack, email,
176
+ or a shared doc — every credential goes through the portal or 1Password,
177
+ never pasted in a message — and no access beyond the named systems.
173
178
  - **§6 Quick-fill checklist** — the one-screen "have this ready" recap.
174
179
 
175
180
  ### 5. Draft `04-access-checklist.md` (internal tracker)
176
181
 
177
- Same items as `03-client-onboarding.md`'s §1 Access and §2 Decisions, reshaped
178
- into one status table: **Item | System | Why we need it | Status | Notes**.
179
- Status is one of HAVE / REQUESTED / MISSING / N/A — set it from what the call
180
- notes and registry profile actually say was granted or promised, never
181
- assumed. This is the doc (and the matching `onboarding.html` section) a
182
- teammate opens to answer "what are we still waiting on from this client?"
183
- without re-reading the call transcript. Update it in the same commit whenever
184
- access lands — it decays fast otherwise.
182
+ Two tables, never one. **§1 Credentials & grants** — one row per *system* we
183
+ need a credential or an access grant for (a login, an OAuth scope, a share, an
184
+ API key): **System | Access we need (minimum role/scope) | Used by | Status |
185
+ Notes**. Every software the client named on the sales call gets a row, even
186
+ when the ask is still MISSING or it is UNKNOWN whether a credential is needed.
187
+ **§2 Decisions & information owed** — VIP lists, approvers, sample data, IT
188
+ intros, answers we owe them: **Item | Who owes it | Why | Status | Notes**. A
189
+ list, a person or a decision is never a §1 row; that mixing is what turns the
190
+ tracker into a wall nobody reads. Status is HAVE / REQUESTED / MISSING /
191
+ UNKNOWN / N/A — set from what the call notes and registry profile actually say
192
+ was granted or promised, never assumed. This is the doc (and the matching
193
+ `onboarding.html` Access tab) a teammate opens to answer "what are we still
194
+ waiting on from this client?" without re-reading the call transcript. Update
195
+ it in the same commit whenever access lands — it decays fast otherwise.
185
196
 
186
197
  - **Capture status, don't invent it.** If a call didn't confirm an item was
187
198
  received, it's MISSING or REQUESTED, not HAVE.
199
+ - **When month one is inbox triage, the SOP's preconditions are §2 rows from
200
+ day one** (`agents/email-gmail-triage/sop.md` or `email-outlook-triage/
201
+ sop.md` § *Preconditions*): the client's written OK that every inbound
202
+ message is read; the BAA / DPA position for a regulated client; the VIP
203
+ list and key phrases; the classification record sheet created and shared
204
+ read-only with the tooling accounts; the sensitive categories (wire, legal,
205
+ health) and how they are handled. The mailbox OAuth grant itself is a §1
206
+ row. Mirror the written-OK ask into `03` §2 (Decisions) — it is the one
207
+ thing the client must say, not grant.
188
208
  - **No credential values or IDs** — status and the 1Password vault *name*
189
209
  only (from `CLIENT.md`), same rule as everywhere else in the repo.
190
- - Mirror the table into `onboarding.html`'s Client tab (a new "Access &
191
- credentials checklist" section) so a developer sees it without opening
192
- `docs/`.
210
+ - Mirror **§1 only** into `onboarding.html`'s Access tab (its own sidebar
211
+ entry, `#access`) so a developer sees it in one screen without opening
212
+ `docs/`. §2 stays in the doc; the Client tab's status snapshot carries the
213
+ open decisions.
193
214
 
194
215
  ### 6. Populate `onboarding.html`
195
216
 
@@ -211,6 +232,17 @@ In short:
211
232
  `<li>` per item, duplicate the template's stub `<li>` as needed. The
212
233
  access table (`ITEM`/`SYSTEM`/`REASON`/`NOTE`, one row per item) is the
213
234
  `04-access-checklist.md` mirror already required in step 5.
235
+ - **Builds tab** — one *systems-level* block per build in scope, duplicating
236
+ the template block (`BUILD_TITLE`, `BUILD_SLUG`, `STATUS`,
237
+ `SOURCE_SYSTEM`/`SECOND_SOURCE`/`DECISION`/`DESTINATION_SYSTEM`/`CHANNEL`
238
+ node labels, `BUILD_CAPTION`, and the *under the hood* rows: `INSTANCE`,
239
+ `WORKFLOW_FILE`, `MODEL`, `LEDGER`, `STACK_NOTES`). Add the matching
240
+ `Builds / <name>` sub-link in the sidebar `.subnav` (href = the block's
241
+ `id="build-<slug>"`). Boxes are **client-safe** — the client's own systems
242
+ by name, ours as "Install Agent", no vendor of ours in the SVG; that detail
243
+ goes only in the collapsed *under the hood* table. Anything not yet built
244
+ is drawn dashed (`.ghost`). This is the picture shown on client update
245
+ calls and Looms, so draw it first.
214
246
  - **Workflows tab** — one diagram block per automation in scope, duplicating
215
247
  the template block (`WORKFLOW_TITLE`, `WORKFLOW_SLUG`, `STATUS`,
216
248
  `TRIGGER`/`FILTER`/`AI_STEP`/`N`/`WRITE`/`NOTIFY` node labels, `CAPTION`).
@@ -259,8 +291,9 @@ tokens or empty bullets.
259
291
  error table, AI specifics, **open questions**, build sequence.
260
292
  - [ ] `03-client-onboarding.md`: access / decisions / info / ongoing / not-asking
261
293
  / quick-fill; minimum roles; "creds in your vault, never a password".
262
- - [ ] `04-access-checklist.md`: same items as `03`, Status column set from
263
- what's actually confirmed (not assumed); mirrored into `onboarding.html`.
294
+ - [ ] `04-access-checklist.md`: §1 systems-only credentials table (every
295
+ sales-call software has a row) + §2 decisions/information; Status set from
296
+ what's actually confirmed (not assumed); §1 mirrored into the Access tab.
264
297
  - [ ] `onboarding.html`: no `REPLACE_WITH_*` tokens left unfilled (or, on an
265
298
  update pass, only the ones the tech-discovery call still hasn't
266
299
  answered); Client tab agrees with `02`, not the other way around.
@@ -119,8 +119,13 @@ write path → exception flow → prod cutover → tuning.>
119
119
  done; §3 can come in parallel during week 1.>
120
120
 
121
121
  ## 1. Access (need before kickoff)
122
- <Per system: the minimum role, how they grant it (OAuth/invite), and that
123
- credentials go into the client's own vault — we never take a password.>
122
+ <Per system: the minimum role, and how they grant it. For OAuth/invite-based
123
+ access, describe the grant. For a straight login (no API), point them at
124
+ their portal's Access tab to submit the username/password directly — and a
125
+ two-factor setup key too, if that login uses 2FA — themselves, on their own
126
+ time; it goes straight into their own 1Password vault, never through us by
127
+ hand. Reserve a live working session for what the form can't cover, e.g. an
128
+ admin-consent OAuth flow they have to click through.>
124
129
 
125
130
  ## 2. Decisions (need before kickoff)
126
131
  <Choices only they can make: thresholds, point of contact, channel name.>
@@ -132,8 +137,9 @@ credentials go into the client's own vault — we never take a password.>
132
137
  <Review-call cadence, their time on the review queue, who approves changes.>
133
138
 
134
139
  ## 5. What we are NOT asking for
135
- <Explicit list: no bank passwords ever, no system password (OAuth only), no
136
- access beyond the named systems.>
140
+ <Explicit list: nothing over Slack, email, or a shared doc — every credential
141
+ goes through the portal's Access tab or 1Password, never pasted in a message;
142
+ no access beyond the named systems.>
137
143
 
138
144
  ## 6. Quick-fill checklist
139
145
  - [ ] <access item invited/ready>
@@ -0,0 +1,100 @@
1
+ ---
2
+ name: gcloud-cli-setup
3
+ description: >-
4
+ Keep gcloud CLI accounts and configurations straight when more than one
5
+ GCP identity is in play on a machine — one named configuration per
6
+ account/client, and a check of the active account before any command
7
+ that touches a project. Use this WHENEVER someone logs into a new GCP
8
+ account, sets up a machine that will touch more than one client's GCP
9
+ project, asks "how do I add another gcloud account", "how do I switch
10
+ accounts", "which gcloud account am I on", or a GCP command runs against
11
+ the wrong project. Reach for it even if the user never says "skill" —
12
+ any time gcloud auth/config state is being set up or checked.
13
+ ---
14
+
15
+ # gcloud-cli-setup — one named configuration per account
16
+
17
+ Never run GCP commands off a single unnamed (`default`) configuration once
18
+ more than one account is in play on a machine. A stray command run against
19
+ the wrong active account can touch the wrong client's project.
20
+
21
+ ## Core rule
22
+
23
+ One **named gcloud configuration** per account/client, never a bare
24
+ `default`:
25
+
26
+ ```
27
+ gcloud config configurations create <name>
28
+ gcloud config configurations activate <name>
29
+ gcloud config set account <email>
30
+ gcloud config set project <project-id>
31
+ ```
32
+
33
+ Pick `<name>` to match the client slug or account purpose (e.g.
34
+ `behaviatherapy`, `installagent`), not the tool ("gcp") or the email local
35
+ part alone.
36
+
37
+ ## Before running any GCP command
38
+
39
+ Confirm which account and project are active — don't assume:
40
+
41
+ ```
42
+ gcloud config configurations list
43
+ gcloud auth list
44
+ ```
45
+
46
+ The row with `IS_ACTIVE = True` (or the `*` in `auth list`) is what every
47
+ subsequent `gcloud` command runs as. If it's not the account/project you
48
+ expect, activate the right configuration first:
49
+
50
+ ```
51
+ gcloud config configurations activate <name>
52
+ ```
53
+
54
+ ## Adding a new account
55
+
56
+ 1. Check what already exists — don't assume a `default` configuration is
57
+ empty or safe to reuse:
58
+ ```
59
+ gcloud config configurations list
60
+ ```
61
+ 2. Create a configuration named for the new account/client, then log in:
62
+ ```
63
+ gcloud config configurations create <name>
64
+ gcloud config configurations activate <name>
65
+ gcloud auth login <email>
66
+ ```
67
+ A browser window opens for sign-in. `gcloud` sets the signed-in account
68
+ active on that configuration automatically.
69
+ 3. Set the project once you know it:
70
+ ```
71
+ gcloud config set project <project-id>
72
+ ```
73
+
74
+ ## Renaming a configuration
75
+
76
+ `gcloud` has no rename command. Recreate it:
77
+
78
+ ```
79
+ gcloud config configurations describe <old-name> # note account + project
80
+ gcloud config configurations create <new-name>
81
+ gcloud config configurations activate <new-name>
82
+ gcloud config set account <email-from-above>
83
+ gcloud config set project <project-from-above>
84
+ gcloud config configurations delete <old-name> # account stays logged in
85
+ ```
86
+
87
+ ## Switching per-terminal without changing the global active configuration
88
+
89
+ ```
90
+ export CLOUDSDK_ACTIVE_CONFIG_NAME=<name>
91
+ ```
92
+
93
+ Useful when running commands for two accounts in different terminal tabs at
94
+ the same time. Or scope a single command with `--configuration=<name>`
95
+ instead of switching anything.
96
+
97
+ ## Related
98
+
99
+ - `ia-cli` — the same "check what's active before you act" discipline
100
+ applies to `ia`'s own client-scoped commands.
@@ -0,0 +1,106 @@
1
+ ---
2
+ name: github-profile
3
+ description: >-
4
+ Force every GitHub action (gh CLI commands, git push/pull against a GitHub
5
+ remote, PR creation, gh api calls) to run under THIS MACHINE's Install Agent
6
+ work account — the one that is a member of the InstallAgent GitHub org —
7
+ never a personal account that is also logged into `gh` on the same machine.
8
+ Resolves the work account from the workspace-root `.github-account` file
9
+ (or from org membership when the file is missing), checks the active `gh`
10
+ account, and switches before the action. Use this WHENEVER a task is about
11
+ to run a `gh` command, a git operation against a GitHub remote, or any
12
+ GitHub API call. Reach for it even if the user never says "skill" — any
13
+ GitHub request on any technician machine.
14
+ ---
15
+
16
+ # github-profile — act as this machine's work account, never the personal one
17
+
18
+ Most technician machines have two GitHub accounts logged into the `gh` CLI:
19
+ the Install Agent work account and a personal one. Only the work account is
20
+ a member of the **InstallAgent** GitHub org. GitHub actions must never run
21
+ under the other one — a PR, an API call or a push under the personal account
22
+ lands on the wrong identity and usually fails with "Repository not found".
23
+
24
+ This skill is bundled into every technician's workspace, so it **never names
25
+ a person or a login**. The login lives in one machine-local file.
26
+
27
+ ## Where the work account is recorded
28
+
29
+ `<workspace-root>/.github-account` — one line, the GitHub login of this
30
+ machine's work account. Nothing else. The workspace root is not a git repo
31
+ and the file is not part of the template bundle, so it never travels to
32
+ another machine.
33
+
34
+ ## Before any GitHub action
35
+
36
+ 1. **Resolve the work account.**
37
+ - If `.github-account` exists at the workspace root, its content is the
38
+ work login. Done.
39
+ - If it does not exist: list the logged-in accounts with
40
+ `gh auth status`, and for each login check org membership:
41
+
42
+ ```
43
+ gh api orgs/InstallAgent/memberships/<login> --jq .state
44
+ ```
45
+
46
+ Exactly one `active` login → that is the work account. Write it to
47
+ `.github-account` so the next task skips this step.
48
+ None → stop and tell the user `gh auth login --hostname github.com`
49
+ is needed for the work account. Do not proceed under the other one.
50
+ More than one → ask the user which one is the work account for this
51
+ machine, then write the file.
52
+
53
+ 2. **Check the active account.**
54
+
55
+ ```
56
+ gh auth status
57
+ ```
58
+
59
+ 3. **If the active `github.com` account is not the work login, switch:**
60
+
61
+ ```
62
+ gh auth switch --hostname github.com --user <work-login>
63
+ ```
64
+
65
+ 4. Only then run the actual command (`gh pr create`, `gh api …`,
66
+ `git push`, …).
67
+
68
+ Do this check-then-switch every time a GitHub action starts a task — the
69
+ active account drifts whenever the user, another tool or another session
70
+ used the personal account in between.
71
+
72
+ ## Git identity
73
+
74
+ Pushes over SSH use the per-repo key (`git config --get core.sshcommand` in
75
+ any InstallAgent clone) and are independent of the `gh` account — a switch
76
+ never fixes or breaks a push. Commits should carry the work account's
77
+ identity so history stays attributable and free of personal addresses:
78
+
79
+ - `user.name` = the work login
80
+ - `user.email` = `<id>+<login>@users.noreply.github.com`
81
+ (`gh api user --jq .id` prints the id while the work account is active)
82
+
83
+ If `git config user.email` in a repo shows something else, **say so and let
84
+ the user decide** — never rewrite their git config unasked.
85
+
86
+ ## Token scope
87
+
88
+ The work account's `gh` token normally carries `repo, read:org, gist,
89
+ admin:public_key`. Org administration (removing a member, reading org
90
+ secrets) and writing under `.github/workflows/` need more — tell the user to
91
+ run `gh auth refresh -h github.com -s admin:org` (or `-s workflow`) rather
92
+ than working around it. Pushing workflow files over SSH is not subject to
93
+ the token scope.
94
+
95
+ ## Offboarding a technician
96
+
97
+ Removing someone's GitHub access is one call under an org admin's account
98
+ and it also drops every team membership:
99
+
100
+ ```
101
+ gh api -X DELETE orgs/InstallAgent/members/<login>
102
+ ```
103
+
104
+ Verify with the members list afterwards. Their machine's
105
+ `.github-account` is theirs to delete; nothing in the bundle references
106
+ them.