@installagent/sdk 0.9.1 → 0.11.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.
@@ -5,10 +5,10 @@ description: >-
5
5
  a two-part terminal brief, where it stands now (by system), then one ranked
6
6
  table of what is wrong and what to do about it. Reads the build repo
7
7
  (CLIENT.md, docs/00-delivery-log.md, evidence/, onboarding.html, AGENT.md
8
- gotchas), local git state (uncommitted, unpushed, open PRs, stray
9
- worktrees), the read-only `ia client` / `ia client-linear` commands, the
10
- calendar, the client's Slack channel, and n8n run health via `ia agent
11
- executions`. Use this WHENEVER someone says "what's the latest on [client]",
8
+ gotchas), `ia client-drift` (one read-only call for the repo against n8n,
9
+ Linear, git and its own drift lint), log vs git and stray worktrees by
10
+ hand, the read-only `ia client` / `ia client-linear` commands, the
11
+ calendar and the client's Slack channel. Use this WHENEVER someone says "what's the latest on [client]",
12
12
  "catch me up on [client]", "where did we leave off", "resume the [client]
13
13
  build", "status of [client]", "what's blocked on [client]", "did anything
14
14
  drift", or opens a `clients/client-[slug]/` repo cold. The brief is a pure
@@ -62,8 +62,8 @@ Run it in this order. Each step is cheap and narrows the next.
62
62
  ### 1. The manifest
63
63
 
64
64
  `cat clients/client-<slug>/CLIENT.md`. It maps every external system.
65
- Note any key that is still a placeholder (`<...>`, or a literal
66
- `client-<slug>`) — an unfilled key is a drift finding, not a detail.
65
+ A key that still holds a placeholder is a drift finding; `ia client-drift`
66
+ (step 3) reports it, so do not hunt for it by hand.
67
67
 
68
68
  ### 2. The repo, in the window
69
69
 
@@ -71,41 +71,72 @@ Note any key that is still a placeholder (`<...>`, or a literal
71
71
  the "what shipped, does it work" record.
72
72
  - `evidence/` — files dated in the window. An accuracy or go-live claim
73
73
  with no evidence file is a risk, not a fact.
74
- - `onboarding.html` — find the status snapshot and its **`AS OF` date**.
75
- Compare that date to the newest log entry.
74
+ - `onboarding.html` — read the status snapshot. `ia client-drift` (step 3)
75
+ checks its **`AS OF` date** against the newest log entry.
76
76
  - `AGENT.md` § *Client-specific gotchas* — the traps for this repo. Carry
77
77
  any that still apply into the risks/next table.
78
78
  - `docs/` index — a high-numbered handoff or decision-log doc
79
79
  (`NN-...-handoff.md`) is usually the freshest single page. Read it.
80
80
 
81
- ### 3. Git state — where work goes missing
81
+ ### 3. `ia client-drift` — the drift checks, in one read
82
82
 
83
83
  ```bash
84
- cd clients/client-<slug>
85
- git status --porcelain # uncommitted work
86
- git log --oneline @{u}..HEAD # committed but never pushed
87
- git log --oneline --since=<window-start>
88
- gh pr list --state open # if the repo pushes to GitHub
89
- git worktree list
84
+ ia client-drift <slug> --json # from the workspace root, or add -w <root>
90
85
  ```
91
86
 
92
- Built-but-unlanded work is the most common real risk in this workspace —
93
- it's the "Git vs reality" row in the drift table below, and it belongs
94
- there even when the count is zero (say "clean" in the row rather than
95
- omitting it). Also check `.claude/worktrees/` — a stale worktree holds a
96
- full duplicate `docs/` tree, and reading the wrong copy produces a
97
- confidently wrong brief.
87
+ Read-only: it reads n8n (workflows, and run *status* only, never run data),
88
+ Linear (queries only), git, `gh` and the repo's own `ci/repo-lint.mjs`. It
89
+ writes nothing. One call makes every drift check in the table below except
90
+ two (step 4):
98
91
 
99
- **A PR that's green and ready to merge is not a passive fact — put it in
100
- the ranked table as an action**, not just a count in the drift row. The
101
- distinction: "3 unpushed commits" is drift (something disagrees with
102
- reality); "PR #25 is green, waiting on a merge click" is a one-line fix,
103
- so it belongs in NEXT-worthy rows even though nothing is technically
104
- wrong yet.
92
+ | `check` | What it compares |
93
+ |---|---|
94
+ | `linear` | Linear vs the delivery log: an issue Done with no entry, or an entry that says shipped while the issue is open |
95
+ | `lint` | the repo's drift rules 12–19, 21 and 22: an `AS OF` date behind the log (12), a dead evidence link or an evidence file no entry names (13), a Builds `workflow_id` no doc names (14), a `CLIENT.md` placeholder (15), stale status words on an active build (16), a dead pointer (17), a generated block behind its source (18), a doc with no `Type:` line (19), the client's access block in `03` not matching `04` §1, or the retired Access tab still in the page (21), work state in a spec (a `Status:` line, an open question with no INS id) or a hand-kept "Next" list in the page (22) |
96
+ | `git`, `open-pr` | uncommitted, untracked or unpushed work, no upstream; open PRs |
97
+ | `active-flag`, `missing-workflow`, `name` | `CLIENT.md` `## Builds` vs n8n: inactive or archived while the repo says live, an id the instance does not have, `SHADOW`/`TEST` still in a live name |
98
+ | `missing-export`, `stale-export`, `orphan-export` | `workflows/` exports vs the instance |
99
+ | `silence`, `last-error` | an active schedule with no recent run; a failed newest run |
100
+
101
+ Each finding has a `level` (`drift`: two sources disagree and one is wrong;
102
+ `check`: a person should look), a `subject`, `sourceA` ≠ `sourceB`, and a
103
+ `hint`. The hint is the Fix cell of the row it becomes.
104
+
105
+ - **A partial report is not a clean one.** The command exits 1 on drift *or*
106
+ when a source could not be read. Every `unreadSources` entry (no
107
+ `N8N_API_KEY`, a key without `execution:read`, no `LINEAR_API_TOKEN`) and
108
+ every per-client `skipped` entry goes into **Could not read**. Never write
109
+ "no drift" from a run that skipped a source.
110
+ - A client with `backlog:` in `CLIENT.md` (no Linear) skips `linear`. Say so.
111
+ - **Built-but-unlanded work is the most common real risk in this
112
+ workspace.** The `git` and `open-pr` findings are the "Git vs reality"
113
+ row, and that row is in the brief even when it is clean (say "clean").
114
+ - **A PR that's green and ready to merge is not a passive fact — put it in
115
+ the ranked table as an action**, not just a count in the drift row.
116
+ "3 unpushed commits" is drift; "PR #25 is green, waiting on a merge
117
+ click" is a one-line fix, so it earns a row even though nothing is wrong.
118
+ - To look deeper into one workflow's finding:
119
+ `ia agent executions <workflowId> -n 20`. Never pass `--data` (run data
120
+ holds full client payloads), and never run a client workflow to "see if
121
+ it works".
122
+
123
+ ### 4. Git — the two checks `ia client-drift` does not make
124
+
125
+ ```bash
126
+ cd clients/client-<slug>
127
+ git log --oneline --since=<window-start> # log vs git
128
+ git worktree list # stray worktrees
129
+ ls .claude/worktrees/ 2>/dev/null
130
+ ```
131
+
132
+ - **Log vs git:** a log entry in the window that claims a deploy or a merge
133
+ needs a matching commit in the window.
134
+ - **Worktrees:** a stale worktree holds a full duplicate `docs/` tree, and
135
+ reading the wrong copy produces a confidently wrong brief.
105
136
 
106
137
  Never commit, never push, never force-push to undo something you find.
107
138
 
108
- ### 4. The `ia` read-only commands
139
+ ### 5. The `ia` read-only commands
109
140
 
110
141
  ```bash
111
142
  ia client <slug> # registry profile + recent calls + delivery log
@@ -116,7 +147,7 @@ ia client-linear <slug> # OPEN issues in the client's Linear project
116
147
  or a referenced doc is missing locally. Do not hand-roll GitHub, Airtable,
117
148
  Linear, or Drive calls — see the `ia-cli` skill.
118
149
 
119
- ### 5. The calendar — the one date the repo cannot be trusted for
150
+ ### 6. The calendar — the one date the repo cannot be trusted for
120
151
 
121
152
  One query: `angello@installagent.com`'s calendar across the surrounding
122
153
  week. Take the client's **next** and **last** meeting from it. Match the
@@ -138,7 +169,7 @@ inside the repo can catch that. Only the calendar can.
138
169
  - **Never rewrite history to match.** A dated delivery-log entry records
139
170
  what was believed then; correct it with a new entry, not an edit.
140
171
 
141
- ### 6. Slack — the client's own words
172
+ ### 7. Slack — the client's own words
142
173
 
143
174
  Read `slack_channel` from `CLIENT.md`. Read the channel back to the window
144
175
  start. The convention is `#client-<slug>`, but real names vary (one has a
@@ -157,42 +188,22 @@ Slack. If you see one, report *that it happened* and that it needs
157
188
  rotating and deleting. Never echo the value into the brief, a file, a
158
189
  commit message, or a Linear issue.
159
190
 
160
- ### 7. n8n run health
161
-
162
- Workflow IDs are **not** in the repo's `workflows/*.json` — those exports
163
- are sanitized, so the `id` field is stripped. They live in the docs:
164
-
165
- ```bash
166
- grep -rIoh '`[A-Za-z0-9]\{16\}`' docs/ evidence/ AGENT.md | sort | uniq -c | sort -rn
167
- ia agent executions <workflowId> -n 20
168
- ```
169
-
170
- A 16-character backticked string is an n8n workflow id. The most-cited one
171
- is usually the live workflow, but confirm it against the tech spec before
172
- you report on it — never guess an id from the client name.
173
-
174
- Report last run, last error, and silence (a workflow that should run daily
175
- and has not run). Flag "built but never published" — an inactive or draft
176
- workflow while the docs or Linear call it live.
177
-
178
- Do **not** pass `--data`: run data holds full client payloads. Do not
179
- manually execute a client workflow to "see if it works".
180
-
181
191
  ## The drift checks
182
192
 
183
- Run every one. Report each as a pair of surfaces that disagree, with file
193
+ Run every one. `ia client-drift` (step 3) makes six of them; two stay by
194
+ hand (step 4). Report each as a pair of surfaces that disagree, with file
184
195
  and line.
185
196
 
186
- | Check | Drift looks like |
187
- |---|---|
188
- | Linear vs delivery log | Issue is Done, no log entry exists — or the log says shipped while the issue sits In Progress |
189
- | `onboarding.html` vs delivery log | The `AS OF` snapshot date is older than the newest log entry |
190
- | Log vs git | An entry claims a deploy or merge with no matching commit in the window |
191
- | Git vs reality | Uncommitted files, unpushed commits, or an open PR — whether or not a log entry claims it shipped. State "clean" here explicitly when there's nothing, rather than omitting the row |
192
- | `CLIENT.md` | A key still holds a placeholder, so every tool that resolves through it is guessing |
193
- | n8n vs docs | Workflow inactive or draft while docs, Linear, or the client believe it is live |
194
- | Evidence | A log entry links `evidence/<file>.md` that does not exist, or an evidence file no entry mentions |
195
- | Worktrees | A `.claude/worktrees/` copy of `docs/` is newer than the tracked one |
197
+ | Check | Made by | Drift looks like |
198
+ |---|---|---|
199
+ | Linear vs delivery log | `ia client-drift` · `linear` | Issue is Done, no log entry exists — or the log says shipped while the issue sits In Progress |
200
+ | `onboarding.html` vs delivery log | `ia client-drift` · `lint` rule 12 | The `AS OF` snapshot date is older than the newest log entry |
201
+ | Git vs reality | `ia client-drift` · `git`, `open-pr` | Uncommitted files, unpushed commits, or an open PR — whether or not a log entry claims it shipped. State "clean" here explicitly when there's nothing, rather than omitting the row |
202
+ | `CLIENT.md` | `ia client-drift` · `lint` rule 15 | A key still holds a placeholder, so every tool that resolves through it is guessing |
203
+ | n8n vs docs | `ia client-drift` · `active-flag`, `missing-workflow`, `name`, the export checks, `silence`, `last-error` | Workflow inactive, archived or silent while docs, Linear, or the client believe it is live |
204
+ | Evidence | `ia client-drift` · `lint` rule 13 | A log entry links `evidence/<file>.md` that does not exist, or an evidence file no entry mentions |
205
+ | Log vs git | **by hand** (step 4) | An entry claims a deploy or merge with no matching commit in the window |
206
+ | Worktrees | **by hand** (step 4) | A `.claude/worktrees/` copy of `docs/` is newer than the tracked one |
196
207
 
197
208
  ## Output — state, then one ranked table
198
209
 
@@ -254,7 +265,8 @@ Rules for the output:
254
265
  gets its own row in the risks/next table so it isn't just reported and
255
266
  forgotten.
256
267
  - **`Could not read` is required** whenever a source failed — an
257
- unauthenticated MCP session, a missing token, no Linear project. A brief
268
+ unauthenticated MCP session, a missing token, no Linear project, an
269
+ `unreadSources` or `skipped` entry from `ia client-drift`. A brief
258
270
  that silently skips Slack reads as "Slack was quiet".
259
271
  - **Never print a secret, key, password, or client PII**, and never a
260
272
  client's dollar amount into anything shared. Point at the system that
@@ -40,9 +40,21 @@ you keep that same build folder's `onboarding.html` in sync:
40
40
  | `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. |
41
41
  | `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. |
42
42
  | `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**. |
43
- | `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. |
43
+ | `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/N/A. This is the **tracker** and the **one source** of access status: §1's Item, System and Why are client words, and the client's table in `03` is generated from them (`node ci/sync.mjs --write`, repo-lint rule 21). |
44
44
  | `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. |
45
45
 
46
+ **Every doc carries a Type line** on the line under its title, so a reader
47
+ knows how long it lives (repo-lint rule 19; `client-template/AGENT.md` §
48
+ docs/). All four are `spec` — true now, edited in place:
49
+
50
+ | File | Line under the title |
51
+ |---|---|
52
+ | `01-overview.md`, `03-client-onboarding.md` | `<!-- Type: spec -->` — the client reads these (on the portal), so the line is hidden |
53
+ | `02-tech-spec.md`, `04-access-checklist.md` | `Type: spec` |
54
+
55
+ On the update pass, keep the line; add it if the first pass left it out.
56
+ The templates in `references/spec-templates.md` already carry it.
57
+
46
58
  Look at the canonical exemplars before writing — match their depth and
47
59
  structure, not their specific domain:
48
60
 
@@ -95,7 +107,9 @@ This skill runs **twice** per engagement, against two different calls in
95
107
  - For content already filled, update only what the tech call firms up,
96
108
  corrects, or adds (a confirmed trigger, a newly-scoped item, a
97
109
  resolved open question) — don't regenerate prose that's already
98
- accurate just because you're touching the file.
110
+ accurate just because you're touching the file. A resolved open
111
+ question: write the answer into the spec, close its Linear issue, and
112
+ drop its INS id from § Open questions.
99
113
  - Leave anything a human has clearly hand-edited since the first pass
100
114
  alone unless the tech call directly contradicts it.
101
115
  - Move resolved items out of `02-tech-spec.md`'s open-questions list
@@ -149,7 +163,12 @@ the Kingdom tech-spec sections that apply:
149
163
  defensive parser fallback.
150
164
  - **Security** — where credentials live, what gets scrubbed from logs.
151
165
  - **Open questions for the build** — the things the call left unresolved. This
152
- section is the most valuable; it prevents building on an assumption.
166
+ section is the most valuable; it prevents building on an assumption. **Each
167
+ one is a Linear issue** in the client's project (the `linear` skill; ask
168
+ before you create issues — Linear is shared): the spec lists only the INS
169
+ ids (`- INS-123 — short title`), never the open work itself. A spec holds no
170
+ work state — no `Status:` line under the title either (build status lives in
171
+ `CLIENT.md` `## Builds`); repo-lint rule 22 warns on both.
153
172
  - **Build sequence** — the order you'll actually implement in.
154
173
 
155
174
  ### 4. Draft `03-client-onboarding.md` (what we need from them)
@@ -173,22 +192,34 @@ overwhelmed:
173
192
  or a shared doc — every credential goes through the portal or 1Password,
174
193
  never pasted in a message — and no access beyond the named systems.
175
194
  - **§6 Quick-fill checklist** — the one-screen "have this ready" recap.
195
+ - **`## Where things stand`** — the last section: only the two marker lines
196
+ `<!-- ACCESS_STATUS_TABLE:START -->` and `<!-- ACCESS_STATUS_TABLE:END -->`.
197
+ Never write the table by hand: after step 5, `node ci/sync.mjs --write`
198
+ builds it from `04` §1, and the client sees it on the portal Access tab.
176
199
 
177
200
  ### 5. Draft `04-access-checklist.md` (internal tracker)
178
201
 
179
202
  Two tables, never one. **§1 Credentials & grants** — one row per *system* we
180
203
  need a credential or an access grant for (a login, an OAuth scope, a share, an
181
- API key): **System | Access we need (minimum role/scope) | Used by | Status |
182
- Notes**. Every software the client named on the sales call gets a row, even
183
- when the ask is still MISSING or it is UNKNOWN whether a credential is needed.
204
+ API key): **Item | System | Why we need it | Status | Notes**. §1 is the one
205
+ source of access status, and the client reads part of it: **Item, System and
206
+ Why we need it are client words** (plain, no tool jargon, no ticket numbers,
207
+ no dollar amounts) — `node ci/sync.mjs --write` builds the client's table in
208
+ `03` from them. **Notes** stays internal: the minimum role/scope, which build
209
+ uses it, chase detail, INS ids. You may add internal columns (`Access we need`,
210
+ `Used by`); they are never shown. A row that is ours only (our vault, our
211
+ Airtable base) gets `—` in Item: it stays internal. Every software the client
212
+ named on the sales call gets a row, even when the ask is still MISSING; a row
213
+ where it is UNKNOWN whether a credential is needed stays internal (`—` in Item)
214
+ until you know — a client row is HAVE, REQUESTED, MISSING or N/A.
184
215
  **§2 Decisions & information owed** — VIP lists, approvers, sample data, IT
185
216
  intros, answers we owe them: **Item | Who owes it | Why | Status | Notes**. A
186
217
  list, a person or a decision is never a §1 row; that mixing is what turns the
187
218
  tracker into a wall nobody reads. Status is HAVE / REQUESTED / MISSING /
188
219
  UNKNOWN / N/A — set from what the call notes and registry profile actually say
189
- was granted or promised, never assumed. This is the doc (and the matching
190
- `onboarding.html` Access tab) a teammate opens to answer "what are we still
191
- waiting on from this client?" without re-reading the call transcript. Update
220
+ was granted or promised, never assumed. This is the doc a teammate opens to
221
+ answer "what are we still waiting on from this client?" without re-reading
222
+ the call transcript. Update
192
223
  it in the same commit whenever access lands — it decays fast otherwise.
193
224
 
194
225
  - **Capture status, don't invent it.** If a call didn't confirm an item was
@@ -204,10 +235,14 @@ it in the same commit whenever access lands — it decays fast otherwise.
204
235
  thing the client must say, not grant.
205
236
  - **No credential values or IDs** — status and the 1Password vault *name*
206
237
  only (from `CLIENT.md`), same rule as everywhere else in the repo.
207
- - Mirror **§1 only** into `onboarding.html`'s Access tab (its own sidebar
208
- entry, `#access`) so a developer sees it in one screen without opening
209
- `docs/`. §2 stays in the doc; the Client tab's status snapshot carries the
210
- open decisions.
238
+ - **Put the line `<!-- ACCESS_CLIENT_WORDS: the client reads Item, System and Why below on the portal -->` above the §1 table** once you have read Item,
239
+ System and Why as the client would: it tells sync that §1 may be shown.
240
+ Without it nothing is generated.
241
+ - **Then run `node ci/sync.mjs --write`** in the repo: it builds the client's
242
+ table (the `ACCESS_STATUS_TABLE` block in `03`) from §1. Never hand-edit
243
+ that block; repo-lint rule 21 warns when it says something else. There is
244
+ no Access tab in `onboarding.html` any more (retired 2026-11-08):
245
+ technicians read `04`. §2 stays in the doc.
211
246
 
212
247
  ### 6. Populate `onboarding.html`
213
248
 
@@ -225,10 +260,9 @@ In short:
225
260
  tokens, `TRIGGER`, `THRESHOLD`, `IDEMPOTENCY`, `INSTANCE`,
226
261
  `STACK_NOTES`) — pulled straight from `02-tech-spec.md`'s architecture
227
262
  summary and idempotency section. Repeating list tokens
228
- (`SCOPE_ITEM`, `PARKED_ITEM`, `STEP`, `DONE_ITEM`, `NEXT_ITEM`) — one
229
- `<li>` per item, duplicate the template's stub `<li>` as needed. The
230
- access table (`ITEM`/`SYSTEM`/`REASON`/`NOTE`, one row per item) is the
231
- `04-access-checklist.md` mirror already required in step 5.
263
+ (`SCOPE_ITEM`, `PARKED_ITEM`, `STEP`) — one `<li>` per item, duplicate
264
+ the template's stub `<li>` as needed. The page has no access table and no
265
+ hand-kept "Next" list: access lives in `04` §1, open work in Linear.
232
266
  - **Builds tab** — one *systems-level* block per build in scope, duplicating
233
267
  the template block (`BUILD_TITLE`, `BUILD_SLUG`, `STATUS`,
234
268
  `SOURCE_SYSTEM`/`SECOND_SOURCE`/`DECISION`/`DESTINATION_SYSTEM`/`CHANNEL`
@@ -251,7 +285,8 @@ In short:
251
285
  - **Public tab** — the client-safe rewrite: tech-agnostic
252
286
  `PUBLIC_SUMMARY`/`TODAY`/`AFTER`/`METRIC`, `PLAIN_STEP`+`PLAIN_DETAIL`
253
287
  pairs (same pipeline as the Client tab's architecture nodes, no tool
254
- names), `PUBLIC_DONE_ITEM`/`PUBLIC_NEXT_ITEM`, `CLIENT_ASK`.
288
+ names), `PUBLIC_DONE_ITEM`, `CLIENT_ASK` (no "Up next" list: the portal
289
+ reads Now / Next / Later from Linear).
255
290
 
256
291
  If a list section has more real items than the template's stub `<li>`s,
257
292
  duplicate the stub; if fewer, delete the extras — don't leave unfilled
@@ -285,12 +320,17 @@ tokens or empty bullets.
285
320
  - [ ] `01-overview.md`: problem → build (plain) → expectations (measurable,
286
321
  hedged); no bare tool names without a gloss.
287
322
  - [ ] `02-tech-spec.md`: schema, node-by-node, idempotency (both halves),
288
- error table, AI specifics, **open questions**, build sequence.
323
+ error table, AI specifics, **open questions** (each a Linear issue; the
324
+ spec lists INS ids only), build sequence; no `Status:` line.
289
325
  - [ ] `03-client-onboarding.md`: access / decisions / info / ongoing / not-asking
290
326
  / quick-fill; minimum roles; "creds in your vault, never a password".
291
327
  - [ ] `04-access-checklist.md`: §1 systems-only credentials table (every
292
- sales-call software has a row) + §2 decisions/information; Status set from
293
- what's actually confirmed (not assumed); §1 mirrored into the Access tab.
328
+ sales-call software has a row; Item / System / Why in client words,
329
+ `—` in Item for an internal row) + §2 decisions/information; Status set
330
+ from what's actually confirmed (not assumed); `node ci/sync.mjs --write`
331
+ run, so the `03` block matches §1 (repo-lint rule 21 clean).
332
+ - [ ] Each of `01`–`04` has its Type line under the title:
333
+ `<!-- Type: spec -->` in `01` and `03`, `Type: spec` in `02` and `04`.
294
334
  - [ ] `onboarding.html`: no `REPLACE_WITH_*` tokens left unfilled (or, on an
295
335
  update pass, only the ones the tech-discovery call still hasn't
296
336
  answered); Client tab agrees with `02`, not the other way around.
@@ -10,10 +10,10 @@ the `client-kingdom/docs/` exemplars.
10
10
 
11
11
  ```markdown
12
12
  # <Project name> — Project Overview
13
+ <!-- Type: spec -->
13
14
 
14
15
  **Prepared for:** <Client legal/dba name>
15
16
  **Prepared by:** Install Agent
16
- **Status:** Proposal, post-discovery
17
17
 
18
18
  ---
19
19
 
@@ -56,9 +56,9 @@ daily review queue that shrinks as the system learns."><br/>
56
56
 
57
57
  ```markdown
58
58
  # Tech Spec — <short system name>
59
+ Type: spec
59
60
 
60
61
  **Audience:** Install Agent engineering. Internal.
61
- **Status:** Pre-implementation, ready for build kickoff.
62
62
  **Source diagram:** docs/<name>-diagram.html
63
63
 
64
64
  ---
@@ -101,7 +101,9 @@ parser fallback, retry policy, rough per-call cost at expected volume.>
101
101
  <Audit log of record; daily/weekly digest; native dashboards.>
102
102
 
103
103
  ## 10. Open questions for the build
104
- <Everything the discovery call left unresolved. Resolve before coding.>
104
+ Each open item is a Linear issue in this client's project (`linear_project` in
105
+ `CLIENT.md`), never a line here: list its INS id below, one per line.
106
+ - INS-<id> — <short title of one thing the call left unresolved>
105
107
 
106
108
  ## 11. Build sequence
107
109
  <The order you'll implement: infra → fixtures → core nodes → rules → AI shadow →
@@ -114,6 +116,7 @@ write path → exception flow → prod cutover → tuning.>
114
116
 
115
117
  ```markdown
116
118
  # Client Onboarding Checklist — <Client name>
119
+ <!-- Type: spec -->
117
120
 
118
121
  <One line: plan on a ~45-min working session; build can start once §1 + §2 are
119
122
  done; §3 can come in parallel during week 1.>
@@ -146,21 +149,33 @@ no access beyond the named systems.>
146
149
  - [ ] <decision made>
147
150
  - [ ] <contact + handle>
148
151
  - [ ] <person available for live linking>
152
+
153
+ ## Where things stand
154
+
155
+ <!-- ACCESS_STATUS_TABLE:START -->
156
+ <!-- ACCESS_STATUS_TABLE:END -->
149
157
  ```
150
158
 
159
+ The two marker lines stay empty here: `node ci/sync.mjs --write` fills them
160
+ from `04` §1 (the client's table on the portal Access tab). Never write the
161
+ table by hand.
162
+
151
163
  ---
152
164
 
153
165
  ## `04-access-checklist.md` (internal — status tracker)
154
166
 
155
167
  ```markdown
156
168
  # Access & Credentials Checklist — <slug>
169
+ Type: spec
157
170
 
158
- Internal tracker: same items as `03-client-onboarding.md`'s §1 Access and §2
159
- Decisions, plus what we actually have. `03` is the **ask** we send the
160
- client; this file is the **tracker** — update it the moment access lands or a
161
- decision gets made, so anyone can answer "what are we still waiting on?"
162
- without re-reading the call notes. Mirror this table into `onboarding.html`'s
163
- Client tab in the same commit.
171
+ Internal tracker, and the one source of access status. `03` is the **ask**
172
+ we send the client; this file is the **tracker** — update it the moment
173
+ access lands or a decision gets made, so anyone can answer "what are we still
174
+ waiting on?" without re-reading the call notes. In §1, **Item, System and Why
175
+ we need it are client words**: the client reads them on the portal Access tab
176
+ (no ticket numbers, no dollar amounts). **Notes** stays internal. `—` in Item
177
+ keeps a row internal. After any change, run `node ci/sync.mjs --write`: it
178
+ rebuilds the client's table in `03` (repo-lint rule 21).
164
179
 
165
180
  No real credential values or IDs here — status and the 1Password vault
166
181
  *name* only (see `CLIENT.md`).
@@ -168,12 +183,22 @@ No real credential values or IDs here — status and the 1Password vault
168
183
  Status legend: **HAVE** · **REQUESTED** (asked, not yet received) ·
169
184
  **MISSING** (not yet asked, or blocking) · **N/A**
170
185
 
186
+ ## §1 — Credentials & grants
187
+
188
+ <!-- ACCESS_CLIENT_WORDS: the client reads Item, System and Why below on the portal -->
189
+
171
190
  | Item | System | Why we need it | Status | Notes |
172
191
  |---|---|---|---|---|
173
- | <e.g. Portal login> | <e.g. Catalyte> | <what it unblocks> | MISSING | <who's chasing it, by when> |
174
- | <e.g. EHR admin user> | <e.g. Lumary> | <what it unblocks> | REQUESTED | <date asked> |
175
- | <e.g. Notification space> | <e.g. Google Chat> | <what it unblocks> | HAVE | <date confirmed> |
176
- | <e.g. Data-handling agreement> | <BAA / DPA> | <legal gate before real data flows> | MISSING | <blocking real-data cutover> |
192
+ | <e.g. A login for your portal> | <e.g. Catalyte> | <what it lets us do for them, in their words> | MISSING | <minimum role; which build; who's chasing it, by when> |
193
+ | <e.g. An admin user for your records system> | <e.g. Lumary> | <what it unblocks> | REQUESTED | <date asked> |
194
+ | <e.g. A space for alerts> | <e.g. Google Chat> | <what it unblocks> | HAVE | <date confirmed> |
195
+ | — | <e.g. 1Password vault `client-<slug>`> | — | HAVE | <ours: never shown to the client> |
196
+
197
+ ## §2 — Decisions & information owed
198
+
199
+ | Item | Who owes it | Why | Status | Notes |
200
+ |---|---|---|---|---|
201
+ | <e.g. Data-handling agreement (BAA / DPA)> | <client> | <legal gate before real data flows> | MISSING | <blocking real-data cutover> |
177
202
 
178
203
  _Last updated: <date> — update in the same commit as any access change._
179
204
  ```
@@ -198,9 +223,10 @@ once (even if the same value is reused verbatim in more than one spot, e.g.
198
223
  `IDEMPOTENCY`, `INSTANCE`, `STACK_NOTES`, `CLIENT_SPECIFIC_RULE`, `DATE`
199
224
  (status-snapshot "as of").
200
225
  - **(repeat)** `SCOPE_ITEM` (Phase 1 scope), `PARKED_ITEM`, `STEP` (build
201
- order, numbered), `DONE_ITEM`, `NEXT_ITEM`.
202
- - **(repeat, one row)** access table: `ITEM`, `SYSTEM`, `REASON`, `NOTE` —
203
- the `04-access-checklist.md` mirror; Status is a badge class, not a token.
226
+ order, numbered). No "Next" list: open work lives in Linear (repo-lint
227
+ rule 22 warns on a hand-kept one).
228
+ - No access table: the Access tab is retired (2026-11-08). Access lives in
229
+ `04-access-checklist.md` §1; the client's table in `03` is generated from it.
204
230
 
205
231
  **Workflows tab** — one whole diagram block duplicated per automation in
206
232
  scope:
@@ -219,7 +245,8 @@ scope:
219
245
  `METRIC`, `DATE` (reused, progress "as of").
220
246
  - **(repeat, paired)** `PLAIN_STEP`+`PLAIN_DETAIL` — same pipeline as the
221
247
  Client tab's architecture nodes, described without tool names.
222
- - **(repeat)** `PUBLIC_DONE_ITEM`, `PUBLIC_NEXT_ITEM`, `CLIENT_ASK`.
248
+ - **(repeat)** `PUBLIC_DONE_ITEM`, `CLIENT_ASK`. No "Up next" list: the
249
+ portal reads Now / Next / Later from Linear.
223
250
  - **`portal-overview` JSON block** (the client portal's Onboarding tab):
224
251
  not tokens you replace one by one — fill the whole JSON (`asOf`,
225
252
  `summary` — one plain paragraph ≤ 280 chars that opens the page —,