@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,235 @@
1
+ ---
2
+ name: cloud-devops
3
+ description: "Cloud infrastructure and DevOps workflow covering AWS, Azure, GCP, Kubernetes, Terraform, CI/CD, monitoring, and cloud-native development."
4
+ category: workflow-bundle
5
+ risk: safe
6
+ source: personal
7
+ date_added: "2026-02-27"
8
+ ---
9
+
10
+ # Cloud/DevOps Workflow Bundle
11
+
12
+ ## Overview
13
+
14
+ Comprehensive cloud and DevOps workflow for infrastructure provisioning, container orchestration, CI/CD pipelines, monitoring, and cloud-native application development.
15
+
16
+ ## When to Use This Workflow
17
+
18
+ Use this workflow when:
19
+ - Setting up cloud infrastructure
20
+ - Implementing CI/CD pipelines
21
+ - Deploying Kubernetes applications
22
+ - Configuring monitoring and observability
23
+ - Managing cloud costs
24
+ - Implementing DevOps practices
25
+
26
+ ## Workflow Phases
27
+
28
+ ### Phase 1: Cloud Infrastructure Setup
29
+
30
+ #### Skills to Invoke
31
+ - `cloud-architect` - Cloud architecture
32
+ - `aws-skills` - AWS development
33
+ - `azure-functions` - Azure development
34
+ - `gcp-cloud-run` - GCP development
35
+ - `terraform-skill` - Terraform IaC
36
+ - `terraform-specialist` - Advanced Terraform
37
+
38
+ #### Actions
39
+ 1. Design cloud architecture
40
+ 2. Set up accounts and billing
41
+ 3. Configure networking
42
+ 4. Provision resources
43
+ 5. Set up IAM
44
+
45
+ #### Copy-Paste Prompts
46
+ ```
47
+ Use @cloud-architect to design multi-cloud architecture
48
+ ```
49
+
50
+ ```
51
+ Use @terraform-skill to provision AWS infrastructure
52
+ ```
53
+
54
+ ### Phase 2: Container Orchestration
55
+
56
+ #### Skills to Invoke
57
+ - `kubernetes-architect` - Kubernetes architecture
58
+ - `docker-expert` - Docker containerization
59
+ - `helm-chart-scaffolding` - Helm charts
60
+ - `k8s-manifest-generator` - K8s manifests
61
+ - `k8s-security-policies` - K8s security
62
+
63
+ #### Actions
64
+ 1. Design container architecture
65
+ 2. Create Dockerfiles
66
+ 3. Build container images
67
+ 4. Write K8s manifests
68
+ 5. Deploy to cluster
69
+ 6. Configure networking
70
+
71
+ #### Copy-Paste Prompts
72
+ ```
73
+ Use @kubernetes-architect to design K8s architecture
74
+ ```
75
+
76
+ ```
77
+ Use @docker-expert to containerize application
78
+ ```
79
+
80
+ ```
81
+ Use @helm-chart-scaffolding to create Helm chart
82
+ ```
83
+
84
+ ### Phase 3: CI/CD Implementation
85
+
86
+ #### Skills to Invoke
87
+ - `deployment-engineer` - Deployment engineering
88
+ - `cicd-automation-workflow-automate` - CI/CD automation
89
+ - `github-actions-templates` - GitHub Actions
90
+ - `gitlab-ci-patterns` - GitLab CI
91
+ - `deployment-pipeline-design` - Pipeline design
92
+
93
+ #### Actions
94
+ 1. Design deployment pipeline
95
+ 2. Configure build automation
96
+ 3. Set up test automation
97
+ 4. Configure deployment stages
98
+ 5. Implement rollback strategies
99
+ 6. Set up notifications
100
+
101
+ #### Copy-Paste Prompts
102
+ ```
103
+ Use @cicd-automation-workflow-automate to set up CI/CD pipeline
104
+ ```
105
+
106
+ ```
107
+ Use @github-actions-templates to create GitHub Actions workflow
108
+ ```
109
+
110
+ ### Phase 4: Monitoring and Observability
111
+
112
+ #### Skills to Invoke
113
+ - `observability-engineer` - Observability engineering
114
+ - `grafana-dashboards` - Grafana dashboards
115
+ - `prometheus-configuration` - Prometheus setup
116
+ - `datadog-automation` - Datadog integration
117
+ - `sentry-automation` - Sentry error tracking
118
+
119
+ #### Actions
120
+ 1. Design monitoring strategy
121
+ 2. Set up metrics collection
122
+ 3. Configure log aggregation
123
+ 4. Implement distributed tracing
124
+ 5. Create dashboards
125
+ 6. Set up alerts
126
+
127
+ #### Copy-Paste Prompts
128
+ ```
129
+ Use @observability-engineer to set up observability stack
130
+ ```
131
+
132
+ ```
133
+ Use @grafana-dashboards to create monitoring dashboards
134
+ ```
135
+
136
+ ### Phase 5: Cloud Security
137
+
138
+ #### Skills to Invoke
139
+ - `cloud-penetration-testing` - Cloud pentesting
140
+ - `aws-penetration-testing` - AWS security
141
+ - `k8s-security-policies` - K8s security
142
+ - `secrets-management` - Secrets management
143
+ - `mtls-configuration` - mTLS setup
144
+
145
+ #### Actions
146
+ 1. Assess cloud security
147
+ 2. Configure security groups
148
+ 3. Set up secrets management
149
+ 4. Implement network policies
150
+ 5. Configure encryption
151
+ 6. Set up audit logging
152
+
153
+ #### Copy-Paste Prompts
154
+ ```
155
+ Use @cloud-penetration-testing to assess cloud security
156
+ ```
157
+
158
+ ```
159
+ Use @secrets-management to configure secrets
160
+ ```
161
+
162
+ ### Phase 6: Cost Optimization
163
+
164
+ #### Skills to Invoke
165
+ - `cost-optimization` - Cloud cost optimization
166
+ - `database-cloud-optimization-cost-optimize` - Database cost optimization
167
+
168
+ #### Actions
169
+ 1. Analyze cloud spending
170
+ 2. Identify optimization opportunities
171
+ 3. Right-size resources
172
+ 4. Implement auto-scaling
173
+ 5. Use reserved instances
174
+ 6. Set up cost alerts
175
+
176
+ #### Copy-Paste Prompts
177
+ ```
178
+ Use @cost-optimization to reduce cloud costs
179
+ ```
180
+
181
+ ### Phase 7: Disaster Recovery
182
+
183
+ #### Skills to Invoke
184
+ - `incident-responder` - Incident response
185
+ - `incident-runbook-templates` - Runbook creation
186
+ - `postmortem-writing` - Postmortem documentation
187
+
188
+ #### Actions
189
+ 1. Design DR strategy
190
+ 2. Set up backups
191
+ 3. Create runbooks
192
+ 4. Test failover
193
+ 5. Document procedures
194
+ 6. Train team
195
+
196
+ #### Copy-Paste Prompts
197
+ ```
198
+ Use @incident-runbook-templates to create runbooks
199
+ ```
200
+
201
+ ## Cloud Provider Workflows
202
+
203
+ ### AWS
204
+ ```
205
+ Skills: aws-skills, aws-serverless, aws-penetration-testing
206
+ Services: EC2, Lambda, S3, RDS, ECS, EKS
207
+ ```
208
+
209
+ ### Azure
210
+ ```
211
+ Skills: azure-functions, azure-ai-projects-py, azure-monitor-opentelemetry-py
212
+ Services: Functions, App Service, AKS, Cosmos DB
213
+ ```
214
+
215
+ ### GCP
216
+ ```
217
+ Skills: gcp-cloud-run
218
+ Services: Cloud Run, GKE, Cloud Functions, BigQuery
219
+ ```
220
+
221
+ ## Quality Gates
222
+
223
+ - [ ] Infrastructure provisioned
224
+ - [ ] CI/CD pipeline working
225
+ - [ ] Monitoring configured
226
+ - [ ] Security measures in place
227
+ - [ ] Cost optimization applied
228
+ - [ ] DR procedures documented
229
+
230
+ ## Related Workflow Bundles
231
+
232
+ - `development` - Application development
233
+ - `security-audit` - Security testing
234
+ - `database` - Database operations
235
+ - `testing-qa` - Testing workflows
@@ -0,0 +1,181 @@
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
+ ## Start here
51
+
52
+ 1. **Identify the template.** Gmail → `agents/email-gmail-triage/`. Outlook or
53
+ 365 → `agents/email-outlook-triage/`. Never build inbox triage from a blank
54
+ canvas.
55
+ 2. **Read that template's `sop.md`.** It is the authority for preconditions,
56
+ the stage table, the gate numbers, and rollback. This skill is the shared
57
+ method; the SOP is the provider-specific contract.
58
+ 3. **Confirm which stage the client is on.** It is not a memory question — the
59
+ `stage` column in the client's classification record sheet, and the `stage=`
60
+ field in the n8n execution log, both answer it.
61
+ 4. **Read the client repo's `CADENCE.md`.** Every promotion is one cadence
62
+ slice, and the surface matrix says what must move in the same commit.
63
+
64
+ ## The two rules that carry the whole program
65
+
66
+ **1. Promotion is config, never node surgery.** One value (`TRIAGE_STAGE` in
67
+ the `⚙️ Stage` node), published, re-exported, committed. Never enable a
68
+ disabled node to promote a client. A disabled node leaves no audit trail and
69
+ cannot answer "what stage is this client on?".
70
+
71
+ **2. A gate is a number plus a zero-tolerance list.** "It looks good" is not a
72
+ gate. Neither is a percentage on its own — 95% correct still permits the one
73
+ error that ends the engagement. Every gate names the errors that are never
74
+ acceptable at any percentage.
75
+
76
+ ## The soak report
77
+
78
+ Week 1's deliverable is not a working workflow — it is a **taxonomy the client
79
+ approves**. Every soak report uses the same tables, so a technician reading
80
+ their second one already knows the shape.
81
+
82
+ Write it to `evidence/YYYY-MM-DD-email-triage-soak-report.md` in the client's
83
+ build repo, from the classification record sheet.
84
+
85
+ **Required tables:**
86
+
87
+ 1. **Volume** — total messages, messages/day, busiest and quietest day. Sets
88
+ the expectation for how fast the later gates can pass.
89
+ 2. **Sender domains** — top 20 by volume, with a share-of-total column, and a
90
+ count of the long tail below them. This is where the taxonomy comes from.
91
+ A domain with 40 messages and no home in the proposed labels is a missing
92
+ category.
93
+ 3. **Proposed disposition/category mix** — what the classifier said, as counts
94
+ and shares. Read it as a hypothesis, not a result.
95
+ 4. **Review-lane rate** — the share the model was not confident about. Above
96
+ ~20% at soak means the taxonomy does not fit the mail yet. Fix that before
97
+ stage 2, not by lowering the confidence floor.
98
+ 5. **Action-lane load** — how many messages/day would be starred or flagged.
99
+ If it is most of the inbox, the automation gives the owner nothing. This
100
+ number is the one clients feel most directly.
101
+ 6. **Proposed taxonomy** — the label/category list, each with a one-line
102
+ definition and its expected volume from table 2. This is the thing the
103
+ client says yes or no to.
104
+ 7. **Open questions** — anything the mail could not settle. Sender roster
105
+ gaps, ambiguous categories, mail whose importance depends on business
106
+ context we do not have.
107
+
108
+ **Then ask the client to approve or change the list, and wait for the answer.**
109
+ It is their mailbox and their vocabulary. A taxonomy we chose alone is a
110
+ taxonomy they will not use, and the gate does not pass without their yes in
111
+ writing.
112
+
113
+ ## Sampling for the precision gates
114
+
115
+ - **Sample at random across the whole window**, not the most recent N. Recent
116
+ mail is the mail the technician has been staring at all week.
117
+ - **Sample size 50** unless the SOP says otherwise. Open each message by its
118
+ `message_id` in the client's own mailbox — that is where the content is
119
+ allowed to live; it never gets copied into the record sheet or the evidence
120
+ file.
121
+ - **A gate can only be sampled from rows written at the current stage.** After
122
+ a promotion the behaviour changed, so earlier rows are a different
123
+ experiment.
124
+ - **Judge against what the owner would have wanted**, not against what the
125
+ prompt says. The prompt is the thing under test.
126
+
127
+ ## What to tell the client
128
+
129
+ Use the `house-voice` skill — the Slack register.
130
+
131
+ - **Before stage 1:** what it reads, that it changes nothing yet, and roughly
132
+ how long. Get the yes.
133
+ - **At the taxonomy gate:** the soak findings in plain language plus the
134
+ proposed list. This is the one place we wait for a reply.
135
+ - **At every promotion:** what changes today, and how they undo it.
136
+ - **When a gate fails:** say so, with the number and what you are changing. A
137
+ client who hears "82%, so I am not moving it forward yet" trusts the next
138
+ promotion. A silent promotion is how a client finds out by noticing a moved
139
+ email — and that conversation costs more than the message you skipped.
140
+
141
+ ## Landing a promotion in the client repo
142
+
143
+ One CADENCE slice, one commit:
144
+
145
+ - `evidence/YYYY-MM-DD-email-triage-stageN-gate.md` — the sample, the counts,
146
+ every miss, the verdict.
147
+ - `docs/02-tech-spec.md` — the stage section.
148
+ - `docs/00-delivery-log.md` — an entry, since something shipped.
149
+ - `onboarding.html` — the Workflows status badge.
150
+ - `workflows/*.json` — re-exported from n8n in the same session.
151
+ - The Linear issue → Done, and the next stage's issue unblocked.
152
+
153
+ Track the four stages as a Linear sub-issue tree with `blockedBy` chains (see
154
+ the `linear` skill), so stage 3 cannot open before stage 2 closes. The chain
155
+ is the enforcement; a checklist in a doc is not.
156
+
157
+ ## Traps
158
+
159
+ - **A live client on an older version is not automatically retro-fitted.**
160
+ Record the exception in that repo's `AGENT.md` § *Client-specific gotchas*
161
+ and leave the running workflow alone until the next change touches it.
162
+ Re-cutting a production inbox to tidy up our own consistency is a risk the
163
+ client did not ask for.
164
+ - **The record sheet is the health signal.** No new rows today means the
165
+ workflow is off, the trigger broke, or a credential expired. Nothing in the
166
+ mailbox will tell you — a triage agent that has stopped looks exactly like a
167
+ quiet inbox.
168
+ - **Don't fix a bad taxonomy by lowering the confidence floor.** A rising
169
+ review lane is the system reporting that the categories do not match the
170
+ mail. Lowering the floor converts a visible problem into a silent one.
171
+ - **A failed execution must never silently drop a message.** Both mail
172
+ triggers advance by date, so a message whose run errored is never re-polled:
173
+ not retried, not labelled, and nothing says so. Every enabled write node
174
+ carries `retryOnFail`. If you add a node that writes to the mailbox, it
175
+ needs the same posture.
176
+ - **`soak` is also the pause switch.** Something looks wrong mid-engagement:
177
+ set the stage back to `soak` and publish. Writes stop, recording continues,
178
+ so the data does not stop while you diagnose.
179
+ - **The first reply draft the owner sees must not already be in their Drafts
180
+ folder.** Generate samples in a test run at the previous stage and paste
181
+ them into the channel.
@@ -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,136 @@
1
+ ---
2
+ name: google-chat-app-setup
3
+ description: >-
4
+ Deploy a Google Chat app (backed by an n8n webhook workflow) in a client's
5
+ own Google Workspace, and open it up to their whole domain — not just the
6
+ person who built it. Covers the two things that aren't obvious from
7
+ Google's docs: the Chat API Configuration screen (webhook, visibility,
8
+ triggers) AND the separate Google Workspace Marketplace SDK "publish as
9
+ Private" step that domain-wide visibility actually requires. Also covers
10
+ the request/response contract for a Workspace-add-on-style Chat app, which
11
+ differs from the plain Chat REST API in three ways that all fail silently
12
+ as "app not responding" in the Chat UI. Use this WHENEVER a client asks for
13
+ an internal Q&A/FAQ bot inside Google Chat, or a technician hits "not
14
+ responding" after wiring a Chat webhook to n8n.
15
+ ---
16
+
17
+ # Google Chat app setup (client Workspace, n8n-backed)
18
+
19
+ Built and proven end-to-end on Behavia Therapy's `behaviatherapy.com`
20
+ Workspace (2026-08-05). Two things Google's own UI doesn't say plainly:
21
+ domain-wide visibility needs a **second** publish step beyond the Chat API
22
+ config, and a Workspace-add-on-style Chat app uses a different request/
23
+ response shape than the plain Chat REST API — get any one of three shapes
24
+ wrong and Chat just says "not responding," no error surfaced anywhere obvious.
25
+
26
+ ## Part 1 — Chat API Configuration (single user works after this)
27
+
28
+ In the GCP project's **Chat API → Configuration** page:
29
+
30
+ 1. **App details** — name, avatar (host the avatar somewhere durable, not a
31
+ throwaway image host).
32
+ 2. **Interactive features** — enable, check "Build this Chat app as a
33
+ Workspace add-on" if you want it usable outside pure 1:1 DMs later (this
34
+ changes the payload shape — see Part 3).
35
+ 3. **Connection settings / triggers** — App URL = your n8n **production**
36
+ webhook URL (`https://<host>/webhook/<path>`), same URL for all trigger
37
+ types (message, added-to-space, removed-from-space) unless you need to
38
+ split them.
39
+ 4. **Visibility** — checkbox "Make this Chat app available to specific
40
+ people and groups in `<domain>`" is the only option here; the page itself
41
+ tells you domain-wide requires Marketplace (Part 2).
42
+ 5. **Logs** — turn on error logging to Cloud Logging; it's the only place
43
+ Google-side failures (bad response shape, auth rejects) show up — n8n's
44
+ own execution log only shows what happened *after* Google delivered the
45
+ request.
46
+ 6. Save. Test with the owner account's own Chat DM first before touching
47
+ visibility — confirms the webhook contract (Part 3) before adding the
48
+ domain-wide complexity of Part 2.
49
+
50
+ ## Part 2 — Publish as Private (domain-wide visibility)
51
+
52
+ Domain-wide visibility is **not** a setting on the Chat API page — it
53
+ requires publishing through the **Google Workspace Marketplace SDK**, in the
54
+ same GCP project:
55
+
56
+ 1. **APIs & Services → Library** → enable **"Google Workspace Marketplace
57
+ SDK."**
58
+ 2. **Marketplace SDK → App Configuration**:
59
+ - **App Visibility: Private** ("only available to users in your domain")
60
+ — this is what makes it domain-wide and skips Google's public-app
61
+ review (review only applies to Public). Leave **Unlisted** unchecked
62
+ so staff can find it by browsing/searching, not just via direct link.
63
+ - **Installation Settings: Individual + Admin Install** — lets any staff
64
+ member add it themselves.
65
+ - **App Integrations**: check **Google Workspace add-on** →
66
+ **HTTP or other deployments** → **Standalone Chat App**, then use the
67
+ **"(Configure Chat API)"** link to point it at the *same* Chat API
68
+ config from Part 1 — don't create a second one. The top-level
69
+ "Deployment ID / Select deployment" field is for a *generic* Workspace
70
+ Add-on (Apps Script) deployment; it stays disabled and unused for a
71
+ Standalone Chat App — that's expected, not a bug.
72
+ - **OAuth Scopes**: leave the two defaults (`userinfo.email`,
73
+ `userinfo.profile`). No extra scopes needed — auth is verified from the
74
+ signed JWT already on every request (Part 3), not via a separate OAuth
75
+ grant.
76
+ - **Developer Information**: real name/site/email — Google emails this
77
+ address about the listing.
78
+ 3. **Save Draft**, then **Publish** (button label may vary — "Publish" or
79
+ equivalent once required fields are filled).
80
+ 4. **Verify with a second person**, not the builder's own account — have
81
+ someone else in the domain find/add the app in Chat. This is the actual
82
+ proof visibility worked; the owner account was already implicitly
83
+ authorized.
84
+
85
+ ## Part 3 — The webhook contract (Workspace-add-on shape)
86
+
87
+ If "Build this Chat app as a Workspace add-on" is checked, the request/
88
+ response shapes are **not** the plain Chat REST API's. All three of the
89
+ following look identical from the Chat UI ("app not responding") but have
90
+ different root causes — check them in order:
91
+
92
+ 1. **Auth**: the bearer JWT's `email` claim is
93
+ `service-<PROJECT_NUMBER>@gcp-sa-gsuiteaddons.iam.gserviceaccount.com`
94
+ — **not** the generic `chat@system.gserviceaccount.com` from the plain
95
+ API. `aud` is your exact webhook URL. Decode the JWT payload (base64url)
96
+ to sanity-check `iss`/`email`/`aud`; full JWKS signature verification is a
97
+ separate hardening step, not required to get this working.
98
+ 2. **Request body**: everything is nested under `body.chat` —
99
+ `body.chat.messagePayload.message.text` /
100
+ `body.chat.messagePayload.space.name` / `body.chat.user`, and event type
101
+ is inferred from which of `messagePayload` / `addedToSpacePayload` /
102
+ `removedFromSpacePayload` is present. The plain API's flat
103
+ `body.type`/`body.message`/`body.space` shape does not apply here.
104
+ 3. **Response body**: must be the nested envelope, not a flat `{"text":
105
+ "..."}`:
106
+ ```json
107
+ {"hostAppDataAction":{"chatDataAction":{"createMessageAction":{"message":{"text":"..."}}}}}
108
+ ```
109
+ A flat `{"text": "..."}` response is silently ignored by Chat (no error,
110
+ no message, nothing) — this is the single easiest thing to get wrong and
111
+ the hardest to diagnose without capturing real traffic, because the n8n
112
+ execution itself shows `success` right up to a malformed expression.
113
+
114
+ **Fastest way to debug a real "not responding" report**: pull the actual
115
+ trigger-node payload from n8n's execution history for that request (not a
116
+ synthetic test payload) and check these three things directly against what
117
+ was captured, in order. Re-run the fix via the MCP `test_workflow` tool with
118
+ that captured payload pinned to the trigger node — confirms the fix
119
+ end-to-end without needing the reporter to retry in Chat again.
120
+
121
+ ## Requirements checklist
122
+
123
+ - [ ] GCP project in the client's own Workspace org (not a personal/InstallAgent project)
124
+ - [ ] Chat API enabled + configured (Part 1), tested against the owner's own DM
125
+ - [ ] Google Workspace Marketplace SDK enabled + published Private (Part 2)
126
+ - [ ] n8n webhook contract matches Part 3 (Workspace-add-on shapes) if that checkbox was ticked
127
+ - [ ] Verified by a second domain user, not just the builder
128
+ - [ ] Cloud Logging error logs turned on for the Chat API
129
+
130
+ ## Known gaps to flag, not silently skip
131
+
132
+ - Real `@mention`s in escalation paths need the person's People API
133
+ `resourceName` (`users/xxxxx`) — not derivable from just an email address.
134
+ - JWT verification here is claims-based, not full JWKS signature
135
+ verification — fine for an internal FAQ bot, not sufficient if the app
136
+ ever touches anything sensitive enough to need real request authentication.