@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,110 @@
1
+ # Delivery contract — template
2
+
3
+ One page you hand to whoever builds the push on the client/vendor side. Fill
4
+ the brackets, delete what doesn't apply, and put the filled copy in the build
5
+ repo's `docs/` so it's the shared reference rather than a Slack message.
6
+
7
+ Modeled on the DriveCentric contract in
8
+ `clients/client-carvision/docs/data-ingestion-automation.md`.
9
+
10
+ ---
11
+
12
+ ## [Client] → Install Agent — daily [source] feed
13
+
14
+ ### Connection
15
+
16
+ | Field | Value |
17
+ |---|---|
18
+ | Host | `sftp.installagent.com` |
19
+ | Port | `2022` |
20
+ | Protocol | SFTP (SSH), **key-based** — no password |
21
+ | Username | `<client>-<source>` (write user) |
22
+ | Private key | delivered via the client's 1Password vault |
23
+ | Upload directory | **the root of the session (`/`)** — no directory prefix |
24
+
25
+ > The session is chrooted; the root **is** your destination. Uploading into a
26
+ > nested path means our workflow never sees the file and silently keeps reading
27
+ > the previous one.
28
+
29
+ ### File
30
+
31
+ **One file, one stable name: `<source>-latest.csv`, overwritten each day.**
32
+
33
+ If [Client] has multiple locations, concatenate them into this single file and
34
+ include a store-identifier column — do not send one file per location.
35
+
36
+ ### Atomic write — required
37
+
38
+ Upload to a temporary name, then rename into place, so our reader never sees a
39
+ half-written file:
40
+
41
+ ```
42
+ put <your-export>.csv <source>-latest.csv.part
43
+ rename <source>-latest.csv.part <source>-latest.csv
44
+ ```
45
+
46
+ The write user has `rename` permission for exactly this.
47
+
48
+ ### Cadence
49
+
50
+ - Once daily, **completed before [HH:MM local]**. Our workflow runs at
51
+ [HH:MM local].
52
+ - Each push must be **that day's export**, covering [state the period, e.g.
53
+ "records through end of yesterday"]. A re-uploaded previous file is worse
54
+ than a missing one — it looks healthy and is not.
55
+
56
+ ### Format
57
+
58
+ - CSV, UTF-8. A BOM is tolerated.
59
+ - Header row required.
60
+ - One record per row; no merged headers, no summary/total rows.
61
+
62
+ ### Columns
63
+
64
+ | Column | Required | Used for |
65
+ |---|---|---|
66
+ | `[JOIN_KEY]` | **Yes — must never be blank** | joining to [the other feed]; rows without it are unrecoverable and dropped |
67
+ | `[CREATED_TS]` | Yes | recency windows |
68
+ | `[ENTITY_ID]` | Yes | de-duplication |
69
+ | `[STATUS]` | Yes | [what it gates] |
70
+ | `[…]` | | |
71
+
72
+ Extra columns are fine and ignored. Full history in the file is fine — we
73
+ window it on our side.
74
+
75
+ ### What changes if a column is missing
76
+
77
+ [State the specific behavioural consequence, e.g. "without the status column
78
+ we cannot distinguish live from dead records, and the [guardrail] never fires."]
79
+ Make this concrete — it's what gets the column added.
80
+
81
+ ---
82
+
83
+ ## Our side — before declaring the feed live
84
+
85
+ - [ ] First real delivery received; **actual storage key inspected** and confirmed at the root prefix
86
+ - [ ] File test-parsed: encoding, real format vs extension, header row, delimiter
87
+ - [ ] Every required column present, under the exact name expected — record which variant matched
88
+ - [ ] Distinct values pulled for each status/category column; rules written against the real vocabulary
89
+ - [ ] Join-key blank rate measured and recorded
90
+ - [ ] Row count and distinct-key count recorded as the first data point for the volume baseline
91
+ - [ ] Coverage window established (what period the file spans) and `lagHours` computed
92
+ - [ ] Snapshot vs change-log determined and written into the tech spec
93
+ - [ ] Reconciled against a second, independent export of the same data
94
+ - [ ] Absolute guards live; relative guards scheduled for calibration once ~3 deliveries exist
95
+ - [ ] Contract copy committed to the build repo's `docs/`
96
+
97
+ ## Email-transport variant
98
+
99
+ For a vendor that only emails scheduled reports:
100
+
101
+ - Destination `data@installagent.com`; filter on **sender + subject**, both
102
+ pinned in the workflow (a subject-only filter eventually catches something
103
+ else).
104
+ - Fetch with a small `limit` and de-duplicate by message id — don't reprocess.
105
+ - Multiple emails per day (e.g. one per store) is normal; state how many are
106
+ expected so a missing one is detectable.
107
+ - Attachment format is the trap here — verify what it actually is, not what
108
+ it's named.
109
+ - No raw customer/personal data by email if there's any alternative. If the
110
+ data is regulated, this transport needs an explicit decision, not a default.
@@ -0,0 +1,134 @@
1
+ # Feed guards — the concrete set
2
+
3
+ The guard set from CarVision's pricing agent, generalized. Live shape:
4
+ `clients/client-carvision/agent-pricing/thresholds.json` → `feedGuards`.
5
+
6
+ Two tiers on purpose: **relative** guards (share of a trailing median) are the
7
+ real instrument but need run history; **absolute** floors need no state and so
8
+ work from the first run. Ship both.
9
+
10
+ ---
11
+
12
+ ## The set
13
+
14
+ | Guard | Tier | Level | Catches |
15
+ |---|---|---|---|
16
+ | `requiredColumns` present | absolute | **trip** | schema change, wrong file |
17
+ | `minRowsHardFloor` | absolute | **trip** | truncated/empty delivery |
18
+ | `minVinsHardFloor` (distinct join keys) | absolute | **trip** | a file with rows but no usable entities |
19
+ | `maxRowsAbsolute` | absolute | **trip** | full history dump |
20
+ | `maxShareOfMedian` | relative | **trip** | same, scaled |
21
+ | `maxLagHours` | absolute | **trip** | a feed that stopped moving |
22
+ | `maxBlankKeyShare` | absolute | **trip** | upstream join-key corruption |
23
+ | `expectedStores` / expected partitions | absolute | **trip** | a location silently dropped out |
24
+ | `minRowsAbsolute` | absolute | *warn* | thin day |
25
+ | `minVinsAbsolute` | absolute | *warn* | thin day |
26
+ | `minShareOfMedian` | relative | *warn* | thin day, scaled |
27
+
28
+ `medianMinHistory` (≈3) is how many prior runs must exist before the relative
29
+ guards evaluate at all.
30
+
31
+ ## Why the low-volume guards only warn
32
+
33
+ They were trips. On a Monday the pipeline blocked, wrote nothing, and the
34
+ client had no output and no way to tell — the sheet just showed Friday's.
35
+
36
+ Two reasons that was wrong, and both generalize:
37
+
38
+ 1. **Volume is seasonal.** Measured across 17 deliveries, the row count tracked
39
+ the client's business activity ~2 days back: weekday 2,300–2,900, Saturday
40
+ ~1,000, Sunday ~200. A flat share-of-median floor trips **every Monday and
41
+ Tuesday, forever**. The four "degraded deliveries" in the original
42
+ calibration notes were two Mondays and two Tuesdays — the weekly cycle, not
43
+ four incidents.
44
+ 2. **The downstream consumer had gotten more robust.** Once scoring drew on an
45
+ accumulated ledger rather than only today's file, a thin file no longer
46
+ starved the calculation. Blocking traded a slightly-biased output for **no
47
+ output, two days in seven**.
48
+
49
+ > **Check #2 before relaxing anything.** The demotion was made on the belief
50
+ > that scoring was ledger-backed — and an audit later found the ledger wasn't
51
+ > reaching the scorer at all, so for a window the relaxation rested on a
52
+ > premise that was false. Verify the robustness you're relying on actually
53
+ > exists, with a number, before you loosen the guard that was compensating for
54
+ > its absence.
55
+
56
+ Upper bounds stay trips regardless: a history dump poisons accumulated state
57
+ and is **not recoverable on the next run**.
58
+
59
+ ## Setting the freshness threshold
60
+
61
+ Set it **above** the routine baseline:
62
+
63
+ ```
64
+ observed content lag, healthy days: 28.5 – 29.4 h
65
+ maxLagHours: 40
66
+ ```
67
+
68
+ 40h catches a feed that has *stopped* — a re-uploaded stale file (two observed
69
+ at 412h), a paused export — while ignoring the routine ~29h lag, which is an
70
+ upstream problem needing an upstream fix. **A guard that fires every morning is
71
+ muted within a week**, at which point you have no guard at all.
72
+
73
+ Compute the lag from the data's own timestamps, not the file's mtime — an
74
+ mtime only tells you when someone uploaded something.
75
+
76
+ ## Calibrating against real deliveries
77
+
78
+ S3 versioning means every past delivery is still there. Replay candidate
79
+ thresholds over the whole history:
80
+
81
+ ```
82
+ For each versioned delivery:
83
+ compute rows, distinct keys, lag, blank-key share, partition count
84
+ evaluate the candidate thresholds
85
+ compare against your own labelling of that day (healthy / degraded)
86
+ ```
87
+
88
+ Acceptance: **every known-degraded day trips, every known-healthy day passes.**
89
+ CarVision's set blocked 7 of 16 historical degraded deliveries with **zero
90
+ false positives** on the 10 healthy days.
91
+
92
+ Then record the evidence *in the config file*, next to the numbers:
93
+
94
+ - the date range and count of deliveries it was calibrated on
95
+ - healthy-day ranges for each metric
96
+ - each degraded day, its numbers, and which guard catches it
97
+ - an explicit note that absolute floors are **scale-dependent** and must be
98
+ re-checked if the client's volume changes materially
99
+
100
+ A threshold with no calibration comment gets "adjusted" by the next person
101
+ until it stops complaining.
102
+
103
+ ## The failure path
104
+
105
+ ```
106
+ guard trips
107
+ ├─ SKIP the destructive step (do not clear the client-facing output)
108
+ ├─ alert a human, with the specific guard and the actual number
109
+ ├─ mark the client-facing surface as stale (produced-at + health indicator)
110
+ └─ leave yesterday's good output in place
111
+ ```
112
+
113
+ Checks worth making on any guard implementation:
114
+
115
+ - **Does the warning tier actually go anywhere?** CarVision computed warning
116
+ text for weeks and sent it nowhere — the branch had no destination node. A
117
+ branch with no destination is not a warning, it's a comment.
118
+ - **Does the trip route around the destructive node, or just before it?** The
119
+ clear-and-rewrite pattern is the dangerous one: if the trip is evaluated
120
+ after the clear, a bad file still wipes good output.
121
+ - **Is the produced-at timestamp on the surface the client actually looks at?**
122
+ Not in the logs. On the sheet, on the page.
123
+
124
+ ## A feed-health record
125
+
126
+ Persist one row per run — timestamp, rows, distinct keys, lag, blank-key share,
127
+ partitions, verdict. It costs almost nothing and gives you three things:
128
+
129
+ 1. the trailing median the relative guards need,
130
+ 2. the seasonality picture you need before setting any threshold,
131
+ 3. a defensible answer when the client asks "has this been happening long?"
132
+
133
+ CarVision keeps it as a `Feed Health` tab next to the client-facing worklist —
134
+ the client can see it too, which turns a support question into a shared fact.