@installagent/sdk 0.1.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 (94) hide show
  1. package/dist/agent-templates.d.ts +90 -0
  2. package/dist/agent-templates.js +211 -0
  3. package/dist/client-build.d.ts +50 -0
  4. package/dist/client-build.js +155 -0
  5. package/dist/client-context.d.ts +40 -0
  6. package/dist/client-context.js +70 -0
  7. package/dist/client-drive.d.ts +67 -0
  8. package/dist/client-drive.js +278 -0
  9. package/dist/client-intake.d.ts +68 -0
  10. package/dist/client-intake.js +189 -0
  11. package/dist/client-linear.d.ts +30 -0
  12. package/dist/client-linear.js +85 -0
  13. package/dist/docs-search.d.ts +44 -0
  14. package/dist/docs-search.js +187 -0
  15. package/dist/doctor.d.ts +43 -0
  16. package/dist/doctor.js +425 -0
  17. package/dist/env-file.d.ts +25 -0
  18. package/dist/env-file.js +69 -0
  19. package/dist/env-fill.d.ts +43 -0
  20. package/dist/env-fill.js +161 -0
  21. package/dist/env-push.d.ts +37 -0
  22. package/dist/env-push.js +137 -0
  23. package/dist/env-registry.d.ts +49 -0
  24. package/dist/env-registry.js +230 -0
  25. package/dist/exec.d.ts +14 -0
  26. package/dist/exec.js +16 -0
  27. package/dist/fathom-webhook.d.ts +44 -0
  28. package/dist/fathom-webhook.js +123 -0
  29. package/dist/fs-utils.d.ts +9 -0
  30. package/dist/fs-utils.js +34 -0
  31. package/dist/gcp-service-account-key.d.ts +37 -0
  32. package/dist/gcp-service-account-key.js +66 -0
  33. package/dist/gemini-api-key.d.ts +47 -0
  34. package/dist/gemini-api-key.js +132 -0
  35. package/dist/git.d.ts +16 -0
  36. package/dist/git.js +29 -0
  37. package/dist/github-token.d.ts +24 -0
  38. package/dist/github-token.js +30 -0
  39. package/dist/index.d.ts +25 -0
  40. package/dist/index.js +28 -0
  41. package/dist/init.d.ts +47 -0
  42. package/dist/init.js +101 -0
  43. package/dist/linear-project.d.ts +81 -0
  44. package/dist/linear-project.js +192 -0
  45. package/dist/new-client.d.ts +32 -0
  46. package/dist/new-client.js +89 -0
  47. package/dist/ping.d.ts +6 -0
  48. package/dist/ping.js +7 -0
  49. package/dist/portal-admin.d.ts +133 -0
  50. package/dist/portal-admin.js +144 -0
  51. package/dist/sync-templates.d.ts +58 -0
  52. package/dist/sync-templates.js +109 -0
  53. package/dist/template-sync.d.ts +55 -0
  54. package/dist/template-sync.js +90 -0
  55. package/dist/templates.d.ts +19 -0
  56. package/dist/templates.js +24 -0
  57. package/dist/wizard.d.ts +78 -0
  58. package/dist/wizard.js +213 -0
  59. package/package.json +30 -0
  60. package/templates/env.example +60 -0
  61. package/templates/workspace-root/.claude/settings.json +39 -0
  62. package/templates/workspace-root/AGENT.md +205 -0
  63. package/templates/workspace-root/AGENTS.md +11 -0
  64. package/templates/workspace-root/CLAUDE.md +63 -0
  65. package/templates/workspace-root/GEMINI.md +24 -0
  66. package/templates/workspace-root/ONBOARDING.md +164 -0
  67. package/templates/workspace-root/README.md +67 -0
  68. package/templates/workspace-root/skills/CLAUDE.md +79 -0
  69. package/templates/workspace-root/skills/client-deliverables/SKILL.md +131 -0
  70. package/templates/workspace-root/skills/client-deliverables/references/package-layout.md +103 -0
  71. package/templates/workspace-root/skills/client-facing-docs/SKILL.md +131 -0
  72. package/templates/workspace-root/skills/client-facing-docs/references/doc-structures.md +81 -0
  73. package/templates/workspace-root/skills/client-llm-setup/SKILL.md +97 -0
  74. package/templates/workspace-root/skills/client-llm-setup/references/guide-template.md +87 -0
  75. package/templates/workspace-root/skills/client-workflow-diagram/SKILL.md +141 -0
  76. package/templates/workspace-root/skills/client-workflow-diagram/references/excalidraw-format.md +140 -0
  77. package/templates/workspace-root/skills/contract-tech-agnostic/SKILL.md +99 -0
  78. package/templates/workspace-root/skills/contract-tech-agnostic/references/Install_Agent_SOW_Template.docx +0 -0
  79. package/templates/workspace-root/skills/design-system/SKILL.md +118 -0
  80. package/templates/workspace-root/skills/design-system/references/tokens.md +139 -0
  81. package/templates/workspace-root/skills/engagement-spec/SKILL.md +272 -0
  82. package/templates/workspace-root/skills/engagement-spec/references/spec-templates.md +220 -0
  83. package/templates/workspace-root/skills/house-voice/SKILL.md +158 -0
  84. package/templates/workspace-root/skills/house-voice/references/source-copy.md +173 -0
  85. package/templates/workspace-root/skills/ia-cli/SKILL.md +87 -0
  86. package/templates/workspace-root/skills/installagent-brand-kit/SKILL.md +112 -0
  87. package/templates/workspace-root/skills/installagent-brand-kit/assets/installagent-logo.svg +1 -0
  88. package/templates/workspace-root/skills/installagent-brand-kit/assets/installagent-mark.svg +1 -0
  89. package/templates/workspace-root/skills/installagent-brand-kit/references/brand-tokens.md +71 -0
  90. package/templates/workspace-root/skills/installagent-brand-kit/references/branded-pdf.md +66 -0
  91. package/templates/workspace-root/skills/installagent-brand-kit/references/excalidraw-red-theme.md +73 -0
  92. package/templates/workspace-root/skills/installagent-brand-kit/scripts/brand.py +175 -0
  93. package/templates/workspace-root/skills/linear/SKILL.md +186 -0
  94. package/templates/workspace-root/skills/tech-call-prep/SKILL.md +141 -0
@@ -0,0 +1,131 @@
1
+ ---
2
+ name: client-facing-docs
3
+ description: >-
4
+ Produce the three client-facing PDFs Install Agent sends to win and kick off
5
+ an engagement: (1) an Executive Overview, (2) a Proposal & Statement of Work,
6
+ and (3) an Onboarding & Intake Checklist. Use this WHENEVER someone says "make
7
+ the client docs", "write the proposal", "draft the SOW", "the overview PDF",
8
+ "onboarding checklist", "send them the three documents", "we need a quote", or
9
+ you're producing the branded PDF set for a client. Reach for it even if
10
+ the user never says "skill": any time the job is turning an agreed scope into
11
+ the polished, on-brand PDF set a decision-maker reads to say yes, this is the
12
+ skill. It is branded via installagent-brand-kit (official logo + brand red),
13
+ takes its content discipline from engagement-spec (overview/onboarding) and
14
+ contract-tech-agnostic (the SOW), and bakes in Install Agent's commercial
15
+ model: one-time build + monthly service + usage-based API credits passed
16
+ through at cost (capped). Output is three PDFs delivered via the client's Google Drive folder.
17
+ ---
18
+
19
+ # Client-facing document set (the 3 PDFs)
20
+
21
+ The polished PDFs a prospect or client actually reads — written for the
22
+ **owner / decision-maker**, not engineering. Three documents, one voice:
23
+
24
+ | File | What it is | Audience |
25
+ |---|---|---|
26
+ | `..._Executive_Overview.pdf` | 1–2 pp: problem → solution → value → phased rollout → investment → next step | Decision-maker |
27
+ | `..._Proposal_and_SOW.pdf` | The signable scope: workstreams, timeline, fees, terms, acceptance, signatures, Exhibit A (systems) | Decision-maker / signer |
28
+ | `..._Onboarding_Checklist.pdf` | Short, low-effort "what we need to start" + what success looks like | Owner + whoever grants access |
29
+
30
+ They are **deliberately a set**: the overview sells the value, the proposal
31
+ commits the scope and price, the checklist makes saying yes feel easy. Diagrams
32
+ (the how-it-works picture, mockups) are produced separately by
33
+ `client-workflow-diagram` + `installagent-brand-kit` and referenced, not embedded.
34
+
35
+ ## Output contract
36
+
37
+ - Three PDFs uploaded to the client's **Google Drive folder** (link in
38
+ `CLIENT.md`) — client repos no longer have a `client-facing/` directory
39
+ (2026-07 baseline) and finished branded exports are not committed to git.
40
+ Build them in a local scratch directory. Named
41
+ `<Client>_<System>_-_Executive_Overview.pdf`, `..._Proposal_and_SOW.pdf`,
42
+ `..._Onboarding_Checklist.pdf`.
43
+ - **Branding is non-negotiable: official logo + brand red, via
44
+ `installagent-brand-kit`** (`scripts/brand.py` → `pdf_hero()`, `pdf_css()`,
45
+ `render_pdf()`). Never a generic glyph or off-brand accent.
46
+ - Section-by-section structure for each doc:
47
+ [`references/doc-structures.md`](references/doc-structures.md).
48
+
49
+ ## Content discipline (which skill governs what)
50
+
51
+ - **Overview & Checklist** → `engagement-spec` rules: client-facing prose stays
52
+ **tech-agnostic** (name a tool only with a plain gloss), outcomes are
53
+ **measurable but honestly hedged** (ranges/ramps, never guarantees).
54
+ - **Proposal & SOW** → `contract-tech-agnostic`: describe deliverables by
55
+ **function and outcome**; the Client's actual systems go in **Exhibit A**, not
56
+ the scope prose. Operator's own implementation tech is never named.
57
+ - **Brand** (color, logo, type, table/callout styling) → `installagent-brand-kit`.
58
+
59
+ ## The commercial model (bake this into the proposal)
60
+
61
+ Install Agent's standard structure — state all three clearly:
62
+
63
+ 1. **One-time build fee** — the fixed Phase-1 engagement (e.g., $18,000), split
64
+ across commencement + acceptance milestones.
65
+ 2. **Monthly service fee** — hosting, monitoring, support, and the continuous
66
+ tuning loop (e.g., $2,000/mo, month-to-month). This does **not** include
67
+ usage-based costs.
68
+ 3. **Third-party API credits — pass-through, capped.** Usage-based services the
69
+ agent relies on (AI model usage; market-data / vehicle-history APIs) are
70
+ billed **at actual cost, no markup, capped at a monthly ceiling** (e.g.,
71
+ $1,000/mo). The client **pays only what's used**; where a provider supports
72
+ it the charge goes **directly to a client card on file**, otherwise Operator
73
+ passes it through at cost with receipts. The cap is **hard** (no overage
74
+ without written approval) and Operator sends a monthly usage summary.
75
+
76
+ Put the credits in the summary table, the payment schedule, a dedicated clause,
77
+ and the "before sending" fill-ins; surface a one-line version in the overview's
78
+ investment block and a card-on-file confirmation in the checklist.
79
+
80
+ ## Make the checklist feel effortless
81
+
82
+ The onboarding checklist must **not feel overwhelming**. Rules:
83
+
84
+ - Mark the few items that are **enough to start** (★); everything else can follow.
85
+ - Put nice-to-haves under an explicit **"Optional — only speeds things up"**
86
+ section (e.g., publish-date export, historical pricing data).
87
+ - Keep client decisions to the **minimum that only they can make** (guardrail
88
+ defaults to confirm; the API-credit card). Don't ask for things that are
89
+ Operator's job to figure out.
90
+ - Include a **"What success looks like"** section with measurable, hedged
91
+ targets so scope is explicit (e.g., "owner's daily pricing drops from ~4 h to
92
+ ~1 h", "+5% gross profit from sharper buying and selling", "backlog cleared /
93
+ pricing never stalls", "the worklist matches the expert on the majority of
94
+ cars"). Frame as targets measured against their real numbers, not guarantees.
95
+
96
+ ## How to build
97
+
98
+ 1. **Gather the agreed scope** — from `engagement-spec` output (`docs/`), the
99
+ SOW summary, or the call. Don't invent scope; capture what was agreed and
100
+ flag open questions.
101
+ 2. **Draft content** per `references/doc-structures.md`, applying the discipline
102
+ above.
103
+ 3. **Render on-brand** with `installagent-brand-kit`: import `scripts/brand.py`,
104
+ build each doc's HTML body (hero via `pdf_hero`, shared CSS via `pdf_css`,
105
+ plus the doc's component CSS), and `render_pdf()` to the client-facing folder.
106
+ The current CarVision set is the working exemplar.
107
+ 4. **Verify**: render pages to PNG (`pdftoppm -png -r 110`) and eyeball — the
108
+ official logo renders, the accent is brand red, the API-credit terms appear
109
+ in all the right places, nothing spills onto a near-empty page, and the SOW
110
+ has every section (extract text and grep to confirm none dropped).
111
+ 5. **Flag placeholders** (`[legal entity]`, `[signatory]`, contact, card-on-file)
112
+ so they're filled before sending.
113
+
114
+ ## Quality rules
115
+
116
+ - **Official logo + brand red, every time** (via brand-kit). No generic glyph.
117
+ - **Tech-agnostic prose; tools only in Exhibit A** (SOW) or with a gloss
118
+ (overview/checklist).
119
+ - **Measurable, hedged outcomes** — never guarantees.
120
+ - **State the full commercial model** including the capped API-credit pass-through.
121
+ - **No secrets / customer data / real VINs** in any doc.
122
+
123
+ ## Before you finish — checklist
124
+
125
+ - [ ] Three PDFs delivered to the client's Drive folder (not committed —
126
+ `client-facing/` no longer exists), official logo + brand red.
127
+ - [ ] Proposal states one-time + monthly + **capped API-credit pass-through**,
128
+ in the summary, payment schedule, and a clause; Exhibit A lists systems.
129
+ - [ ] Overview is value-first and tech-agnostic; checklist is short with ★,
130
+ Optional, ≤2 confirmations, and a "what success looks like" section.
131
+ - [ ] Previewed as PNG; SOW text checked for completeness; placeholders flagged.
@@ -0,0 +1,81 @@
1
+ # Document structures (section-by-section)
2
+
3
+ The shape each of the three PDFs should take. Adapt the content to the
4
+ engagement; keep the structure and discipline. The current CarVision set
5
+ (`client-carvision/pricing-project/client-facing/`) is the working exemplar.
6
+
7
+ ## 1 · Executive Overview (1–2 pages)
8
+
9
+ Value-first, tech-agnostic, for the decision-maker.
10
+
11
+ 1. **Hero** — official logo, kicker ("Prepared for <Client>"), title, one-line
12
+ sub that names the outcome.
13
+ 2. **The opportunity** — the problem in their words, quantified (time lost,
14
+ margin left on the table). A concrete example lands it.
15
+ 3. **What we'll build** — the solution in plain English; a 3–5 step "how a day
16
+ works" strip. State the human-in-the-loop ("recommends; a person approves").
17
+ 4. **Why it's worth real money** — 2–3 stat cards (time saved, margin/ROI,
18
+ backlog), with an "illustrative, confirmed by backtest" footnote.
19
+ 5. **A phased, low-risk rollout** — Phase 1 (now, fixed price) / Phase 2 / Phase
20
+ 3, with one honest expectation-setting callout.
21
+ 6. **The investment** — the one-time and monthly figures as cards, **plus a line
22
+ for the capped API-credit pass-through** ("up to $X/mo, at cost, you pay only
23
+ what's used"). Point to the proposal for terms.
24
+ 7. **Where this goes** — the broader vision, briefly.
25
+ 8. **Next step** — what happens on a yes.
26
+
27
+ ## 2 · Proposal & Statement of Work
28
+
29
+ Signable. Functional language; tools in Exhibit A. Sections:
30
+
31
+ 1. **Summary** — one paragraph + a fee table: one-time build, monthly service,
32
+ **third-party API credits (up to $X/mo, pass-through at cost)**.
33
+ 2. **Background & objectives** — current state and the goal.
34
+ 3. **Scope of work** — numbered workstreams, each with a **Deliverable** line.
35
+ Describe by function ("a daily review application"), not implementation.
36
+ 4. **Out of scope (this phase)** — autonomous action, write-back, etc.; and that
37
+ usage-based API costs are pass-through under the credits clause, not the fee.
38
+ 5. **Later phases** — context only, separately scoped.
39
+ 6. **Timeline** — indicative windows, labeled estimates not commitments.
40
+ 7. **Investment & payment schedule** — milestone table (commencement /
41
+ acceptance / monthly) **plus a pass-through row** ("at cost, ≤ $X/mo").
42
+ 8. **What the ongoing service includes** — and explicitly that it excludes
43
+ usage-based API costs (→ the credits clause).
44
+ 9. **Third-party API credits (pass-through)** — the full clause: at actual cost,
45
+ no markup, **capped at $X/mo**; pay only what's used; billed to a client card
46
+ where supported else passed through with receipts; hard cap (no overage
47
+ without written approval); monthly usage summary.
48
+ 10. **Client responsibilities** — access, the expert's time, point of contact.
49
+ 11. **Acceptance criteria** — objective, testable.
50
+ 12. **Data handling & confidentiality** — secured infra, no customer data in
51
+ shared repos, on-prem option noted if relevant.
52
+ 13. **Assumptions.**
53
+ 14. **Term, ownership & termination** — ownership on full payment; month-to-month
54
+ service; a definitive agreement supersedes.
55
+ 15. **Acceptance** — signature blocks for both parties + a "before sending —
56
+ fill in" note (entity, signatory, contact, payment split, **API-credit card
57
+ on file**).
58
+ - **Exhibit A — Systems in scope** — the table that names the Client's actual
59
+ products (the only place tool names belong in the SOW).
60
+
61
+ ## 3 · Onboarding & Intake Checklist
62
+
63
+ Short. Low-effort. Explicitly not overwhelming. Sections:
64
+
65
+ - **Intro** — "very little needed; most of it the expert already produces; the ★
66
+ items are enough to start."
67
+ - **Legend** — role chips (who) + ★ = enough to start.
68
+ - **A · The data we'll connect to** — the core access/exports (★ the essentials).
69
+ - **B · The expert's pricing know-how** — their documented logic / knowledge base.
70
+ - **C · Optional — only speeds things up** — nice-to-haves (publish dates,
71
+ historical data); explicitly "we can start and go live without these."
72
+ - **D · Two quick confirmations** — only decisions they must make: guardrail
73
+ defaults to confirm, and the **API-credit card on file** (capped at $X/mo).
74
+ - **E · What success looks like** — measurable, hedged targets (time saved,
75
+ +% profit, no-stall/backlog cleared, recommendation parity). "Targets measured
76
+ against your real numbers, not guarantees."
77
+ - **Closing** — how data is handled securely + a contact.
78
+
79
+ Things to keep OUT of the checklist (Operator's job, not the client's): building
80
+ the competitor/trust list, standing up the shared channel, the expert's tuning
81
+ time, internal hosting. Don't ask the client for them.
@@ -0,0 +1,97 @@
1
+ ---
2
+ name: client-llm-setup
3
+ description: >-
4
+ Produce the client-facing "Your AI Workspace" leave-behind guide — the
5
+ branded document a client keeps after Install Agent sets up their own
6
+ Claude workspace (projects, custom instructions, connectors, data rules) in
7
+ week 1. Takes the 2–3 chosen use cases and drafted project instructions and
8
+ renders them into the guide template, personalized to the client, delivered
9
+ to their Drive folder. Use this WHENEVER prepping or following up the
10
+ client LLM-setup session, or someone says "make the Claude guide for
11
+ [client]", "client AI workspace handout", "leave-behind for the LLM
12
+ session", "set up [client]'s Claude projects". Reach for it even if the
13
+ user never says "skill" — turning a client's use cases into their
14
+ personalized Claude setup guide. This deliverable deliberately names Claude
15
+ (the tech-agnostic rule governs contracts, not a guide whose subject IS the
16
+ tool).
17
+ ---
18
+
19
+ # Client LLM setup — the leave-behind guide
20
+
21
+ The internal runbook (team hub → Techs → Client LLM setup) covers the
22
+ session itself. This skill produces the artifact the client keeps: a
23
+ short, personalized guide to the workspace we just configured, written so
24
+ the person who *wasn't* on the session can still use it Monday morning.
25
+
26
+ ## Inputs (from the technician's prep)
27
+
28
+ - **Client slug** — for the registry profile (voice, facts, contact) and
29
+ build repo (`clients/client-<slug>/`).
30
+ - **The 2–3 use cases** chosen from the discovery call, each with its
31
+ drafted project instructions.
32
+ - **Plan recommended** (Pro / Team) and whether connectors (Drive/Gmail)
33
+ are part of the setup.
34
+
35
+ If the use cases or instructions don't exist yet, that's the runbook's
36
+ prep step — help draft them first (registry profile for facts, verified
37
+ against the client's website, never a transcript spelling).
38
+
39
+ ## Workflow
40
+
41
+ 1. **Fill the template** —
42
+ [`references/guide-template.md`](references/guide-template.md).
43
+ Personalize every section: the client's name, their use cases, their
44
+ actual project names, their data rules. Delete sections that don't
45
+ apply (e.g. connectors, Team administration for a solo Pro user).
46
+ No `REPLACE_WITH_*` marker survives.
47
+ 2. **Write it in the client's register.** Reading level: a busy office
48
+ manager, not a developer. Every instruction is "click this, type
49
+ this"; every example uses *their* documents and vocabulary from the
50
+ call notes. Plain English; short sections; zero AI jargon ("project"
51
+ and "chat" are fine; "context window" is not).
52
+ 3. **Render it branded.** Install Agent brand per
53
+ `installagent-brand-kit` (logo, brand red, print-clean) — same
54
+ pipeline as the `client-facing-docs` PDFs. The guide is a PDF (or a
55
+ single self-contained HTML if the client prefers links), never a raw
56
+ markdown file.
57
+ 4. **Deliver to their Drive folder** (link in `CLIENT.md`) — branded
58
+ deliverables never live in git. Stage the source markdown in the
59
+ build repo only if asked; the Drive copy is canonical.
60
+ 5. **Log it.** The setup session + guide is a shipped deliverable:
61
+ append `docs/00-delivery-log.md` in the build repo.
62
+
63
+ ## The guide's fixed shape
64
+
65
+ Seven sections, template-enforced: **Welcome** (what this workspace is,
66
+ one paragraph) · **Your projects** (one block per project: what it's
67
+ for, how to start, a worked example with their material) · **Daily
68
+ habits** (the 3 moves: pick the right project, give it the raw material,
69
+ ask for changes instead of settling) · **What to share / what to keep
70
+ out** (the data rules, verbatim from the session) · **When it's wrong**
71
+ (iterate, don't abandon — and what to tell us) · **Getting help**
72
+ (their Install Agent contact + Slack channel) · **Account basics**
73
+ (plan, billing is theirs, adding seats).
74
+
75
+ ## Quality rules
76
+
77
+ - **Their hands, not ours.** The guide never says "we'll do this for
78
+ you" about daily usage — the workspace is theirs. Our role appears
79
+ only in Getting help and maintenance-mode framing.
80
+ - **Data rules are non-negotiable content.** The what-to-keep-out list
81
+ ships in every guide, tuned to their industry (a contractor's version
82
+ names subcontractor pricing; a clinic's names patient records —
83
+ HIPAA-adjacent clients get the strict version).
84
+ - **No credentials, no client customer data, no internal Install Agent
85
+ paths/tools** (n8n, registry, repo names) anywhere in the guide.
86
+ - **Facts verified against the registry profile's Internal notes** —
87
+ never propagate a transcript mis-spelling into a branded PDF.
88
+
89
+ ## Before you finish — checklist
90
+
91
+ - [ ] Every template marker replaced; inapplicable sections deleted.
92
+ - [ ] One project block per configured project, with a worked example
93
+ in the client's own vocabulary.
94
+ - [ ] Data rules present and industry-tuned.
95
+ - [ ] Branded per installagent-brand-kit; renders clean in print.
96
+ - [ ] Delivered to the client's Drive folder; delivery log appended.
97
+ - [ ] Readable cold by someone who missed the session.
@@ -0,0 +1,87 @@
1
+ # Your AI Workspace — REPLACE_WITH_CLIENT_NAME
2
+
3
+ > Prepared by Install Agent · REPLACE_WITH_DATE
4
+ > Your contact: REPLACE_WITH_TECH_NAME — REPLACE_WITH_CONTACT_CHANNEL
5
+
6
+ <!--
7
+ TEMPLATE RULES (delete this comment block when filling):
8
+ - Audience: the client's daily user (office manager / PM), reading cold.
9
+ - Plain English. "Project" and "chat" are the only tool words allowed.
10
+ - Every example uses THEIR documents and vocabulary from the call notes.
11
+ - Delete sections that don't apply. No REPLACE_WITH_* marker survives.
12
+ - Render branded (installagent-brand-kit) → PDF → client's Drive folder.
13
+ -->
14
+
15
+ ## Welcome
16
+
17
+ We've set up a Claude workspace for REPLACE_WITH_COMPANY — your own AI
18
+ assistant, configured for how your business actually works. It's on your
19
+ account, it's yours to keep, and everything in this guide was set up
20
+ live in our session on REPLACE_WITH_SESSION_DATE. Ten minutes a day with
21
+ it will save you hours a week; this guide shows you exactly where those
22
+ hours are.
23
+
24
+ ## Your projects
25
+
26
+ Open Claude and you'll see these projects in the left sidebar. Each one
27
+ already knows about your business and its job — always start your chat
28
+ inside the right project, not in a blank chat.
29
+
30
+ ### REPLACE_WITH_PROJECT_1_NAME
31
+
32
+ **What it's for:** REPLACE_WITH_ONE_SENTENCE.
33
+
34
+ **How to use it:** REPLACE_WITH_CLICK_BY_CLICK — e.g. "Open the project,
35
+ attach the REPLACE_WITH_THEIR_DOCUMENT, and type what you need."
36
+
37
+ **Try it now:** REPLACE_WITH_WORKED_EXAMPLE_PROMPT — a real first message
38
+ using their material, quoted so they can copy it.
39
+
40
+ <!-- Repeat the block above per project (2–3 total). -->
41
+
42
+ ## Three habits that make it work
43
+
44
+ 1. **Pick the right project first.** Each project carries its own
45
+ knowledge — a blank chat knows nothing about your business.
46
+ 2. **Give it the raw material.** Attach the actual document, paste the
47
+ actual email. More real input, better output — always.
48
+ 3. **Ask for changes instead of settling.** "Shorter", "more formal",
49
+ "redo it as a table" — treat the first draft as a first draft.
50
+
51
+ ## What to share — and what to keep out
52
+
53
+ Treat a chat like an email to a trusted contractor.
54
+
55
+ **Fine to share:** REPLACE_WITH_INDUSTRY_TUNED_LIST — business documents,
56
+ drafts, schedules, the kinds of files you attach in normal work email.
57
+
58
+ **Keep out, always:**
59
+
60
+ - Passwords or login details — for anything, ever.
61
+ - REPLACE_WITH_INDUSTRY_SENSITIVE_ITEMS (e.g. customer payment details,
62
+ patient records, anything under an NDA).
63
+
64
+ Your projects have these rules built in as reminders, but the habit is
65
+ yours.
66
+
67
+ ## When the answer is wrong
68
+
69
+ It will be, sometimes. Don't abandon the chat — say what's wrong ("the
70
+ totals don't match the attached invoice — recheck them") and it will
71
+ correct course. If a project keeps missing on the same kind of task,
72
+ tell us: tuning the project takes us minutes and it's part of your
73
+ engagement.
74
+
75
+ ## Getting help
76
+
77
+ - **Anything about this workspace:** message REPLACE_WITH_TECH_NAME in
78
+ REPLACE_WITH_SLACK_CHANNEL_OR_EMAIL.
79
+ - **Weekly check-in:** we'll ask how the workspace is working as part of
80
+ your regular update — bring the wins and the misses.
81
+
82
+ ## Account basics
83
+
84
+ - Your plan: REPLACE_WITH_PLAN. Billing is on your card, managed at
85
+ claude.com — Install Agent never holds your login.
86
+ - Adding a teammate: REPLACE_WITH_SEAT_INSTRUCTIONS (Team plan) /
87
+ "talk to us about moving to a Team plan" (Pro).
@@ -0,0 +1,141 @@
1
+ ---
2
+ name: client-workflow-diagram
3
+ description: >-
4
+ Produce an Excalidraw workflow/architecture diagram for a client automation —
5
+ the stage-column flow that goes in a build folder's docs/ and a pitch
6
+ deck. Use this WHENEVER someone says "diagram this", "draw the workflow",
7
+ "make the architecture diagram", "visualize the pipeline", "we need a picture
8
+ for the deck/overview", or you're adding a diagram to client-[slug]/docs/. Also use
9
+ it when a tech spec or overview references a diagram that doesn't exist yet.
10
+ Reach for it even if the user never says "skill": any time the job is turning
11
+ a workflow/architecture description into an editable .excalidraw file (and an
12
+ exported image) in Install Agent's house diagram style, this is the skill. It
13
+ outputs valid Excalidraw JSON laid out as left-to-right stage columns, with
14
+ nodes named using the n8n emoji convention, matching the client-kingdom
15
+ diagram exemplars.
16
+ ---
17
+
18
+ # Client workflow diagram (Excalidraw)
19
+
20
+ Turn a workflow or architecture description into an editable Excalidraw diagram
21
+ that reads left-to-right as **stage columns** — the house style used in
22
+ `client-kingdom/diagrams/`. Two flavors per engagement:
23
+
24
+ - **Client-facing** (`<system>-client.excalidraw`) — simple, outcome-oriented,
25
+ goes in `01-overview.md` and the pitch deck. Few boxes, plain labels.
26
+ - **Internal** (`<system>-internal.excalidraw`) — detailed, node-by-node, mirrors
27
+ the tech spec. For engineering.
28
+
29
+ A diagram is a view of the spec, not a separate source of truth. When the spec
30
+ changes, update the diagram in the same pass — a stale diagram is worse than
31
+ none.
32
+
33
+ ## Output contract
34
+
35
+ - **In client build repos (2026-07 baseline): the Workflows tab of
36
+ `client-<slug>/onboarding.html`** — one inline SVG per automation build,
37
+ stage-column layout, Install Agent design system (the template ships the
38
+ `dg-*` CSS, a placeholder diagram block to duplicate, and per-diagram
39
+ ⬇ SVG / ⬇ PNG download buttons that export a self-contained file, plus a
40
+ ⬇ PDF — ALL WORKFLOWS button that bundles every diagram into one
41
+ print-to-PDF document). Client
42
+ repos no longer have a `diagrams/` directory and `.excalidraw` sources are
43
+ no longer committed there. A standalone self-contained HTML file at
44
+ `docs/<system>-<audience>-diagram.html` is still fine when a diagram needs
45
+ to travel on its own. The Excalidraw guidance below remains for pitch-deck
46
+ images and legacy repos.
47
+ - When producing Excalidraw (decks/legacy), the file is valid Excalidraw JSON (opens cleanly at excalidraw.com and in the
48
+ Excalidraw VS Code / Obsidian plugins). Schema + a paste-ready skeleton:
49
+ [`references/excalidraw-format.md`](references/excalidraw-format.md).
50
+ - Exemplars to match for layout and density:
51
+ - `client-kingdom/diagrams/bookkeeping-workflow.excalidraw` — four stage
52
+ columns (Bank Ingestion · n8n Workflow · QuickBooks · Exception Review).
53
+ - `client-kingdom/diagrams/estimate-automation-client.excalidraw` vs
54
+ `…-internal.excalidraw` — the simple/detailed split for the same system.
55
+ - `client-kingdom/diagrams/build-estimate-diagrams.py` — precedent for
56
+ **generating** Excalidraw JSON from a Python script when a diagram is big or
57
+ regenerated often. Prefer this for anything beyond ~15 elements.
58
+
59
+ ## How to build it
60
+
61
+ ### 1. Get the stages and nodes from the spec
62
+
63
+ Read `02-tech-spec.md` (or the description you were given). Identify:
64
+
65
+ - **Stages** = the vertical columns, left to right (e.g. *Ingestion →
66
+ Orchestration → Destination → Exception/Review*). Usually 3–5.
67
+ - **Nodes** within each stage = the boxes (trigger, normalize, dedup, rules, AI,
68
+ write, log, alert).
69
+ - **Flow** = arrows between nodes, including the branch to the exception path.
70
+
71
+ ### 2. Lay out as stage columns
72
+
73
+ - One tall rounded **container rectangle** per stage, titled at the top
74
+ (house palette: stroke `#364fc7`, fill `#dbe4ff` for containers).
75
+ - **Node boxes** stacked inside each container, top to bottom in flow order.
76
+ - Columns left→right in pipeline order; arrows mostly flow rightward, with the
77
+ low-confidence/exception branch dropping to its own column.
78
+ - Keep spacing generous and consistent (see the skeleton for x/y math). Readability
79
+ beats density — especially on the client-facing version.
80
+
81
+ ### 3. Name nodes with the emoji convention
82
+
83
+ Use the same leading-emoji node names as the workflows (from
84
+ `team-n8n-workflows/AGENT.md`), so the diagram and the n8n canvas match:
85
+
86
+ | Emoji | Meaning |
87
+ |---|---|
88
+ | 📬 📡 ⏰ | trigger / watcher / schedule |
89
+ | 🔍 🚦 | filter / gate / decision |
90
+ | 🔧 🧮 | transform / code |
91
+ | 🤖 | AI / LLM call |
92
+ | 🔀 🔗 | branch / merge |
93
+ | ✅ 🏷️ 🧾 | write / tag / record |
94
+ | 📨 📣 ✏️ | notify / output / draft |
95
+ | 📋 | log |
96
+ | 🗑️ 🚨 | destructive / alert |
97
+
98
+ Client-facing diagrams can soften jargon (say "AI categorizes" not the node
99
+ name), but keep the same shapes and flow as the internal one so they're
100
+ obviously the same system.
101
+
102
+ ### 4. Choose hand-authored vs. generated
103
+
104
+ - **≤ ~15 elements, one-off** → hand-author the JSON from the skeleton.
105
+ - **Bigger, or you'll regenerate it as scope shifts** → write a small Python
106
+ generator like `build-estimate-diagrams.py`: define stages/nodes as data, emit
107
+ elements in a loop, dump JSON. Far easier to keep in sync than hand-editing 60
108
+ elements.
109
+
110
+ ### 5. Export an image for the deck
111
+
112
+ The `.excalidraw` is the editable source of truth and is committed. For the pitch
113
+ deck / overview, export a PNG or SVG (excalidraw.com → Export image, or the CLI/
114
+ plugin) and place it alongside. Keep the `.excalidraw` — never ship only the PNG.
115
+
116
+ ## Quality rules
117
+
118
+ - **The .excalidraw is source; images are exports.** Commit the JSON; regenerate
119
+ images from it.
120
+ - **Match the spec.** Every box and arrow corresponds to something in
121
+ `02-tech-spec.md`. If they disagree, one of them is wrong — fix both.
122
+ - **Two audiences, one shape.** Client and internal versions share layout and
123
+ flow; they differ in detail and labels, not structure.
124
+ - **Emoji node names** match the n8n convention so diagram ↔ canvas line up.
125
+ - **No secrets or real customer data** baked into labels (root AGENT.md). Use
126
+ role names ("the client's bank accounts"), not account numbers.
127
+ - **Validate before commit:** `python -m json.tool <file>.excalidraw` parses, and
128
+ it opens at excalidraw.com.
129
+
130
+ ## Before you finish — checklist
131
+
132
+ - [ ] Valid JSON; opens in Excalidraw.
133
+ - [ ] Laid out as left-to-right stage columns with titled containers.
134
+ - [ ] Nodes use the emoji naming convention; arrows show the exception branch.
135
+ - [ ] Client-facing and internal versions share the same flow.
136
+ - [ ] Lives in the Workflows tab of `client-<slug>/onboarding.html` (or a
137
+ self-contained HTML file in `docs/` if it must travel alone);
138
+ `.excalidraw` only for decks/legacy — never a `diagrams/` dir, which no
139
+ longer exists in the baseline. Download buttons wired (`data-svg` /
140
+ `data-fmt` / `data-name`); image exported for the deck if needed.
141
+ - [ ] No account numbers / PII / secrets in any label.