@installagent/sdk 0.9.0 → 0.10.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 (28) hide show
  1. package/dist/agent-mirror.d.ts +28 -0
  2. package/dist/agent-mirror.js +45 -20
  3. package/dist/client-drift.d.ts +120 -0
  4. package/dist/client-drift.js +556 -0
  5. package/dist/index.d.ts +3 -2
  6. package/dist/index.js +3 -2
  7. package/dist/linear-project.d.ts +18 -0
  8. package/dist/linear-project.js +43 -0
  9. package/dist/template-sync.d.ts +14 -0
  10. package/dist/template-sync.js +27 -0
  11. package/package.json +1 -1
  12. package/templates/workspace-root/AGENT.md +2 -0
  13. package/templates/workspace-root/AGENTS.md +10 -8
  14. package/templates/workspace-root/GEMINI.md +9 -21
  15. package/templates/workspace-root/ONBOARDING.md +3 -1
  16. package/templates/workspace-root/skills/CLAUDE.md +2 -2
  17. package/templates/workspace-root/skills/README.md +12 -4
  18. package/templates/workspace-root/skills/client-facing-docs/SKILL.md +3 -0
  19. package/templates/workspace-root/skills/client-latest/SKILL.md +75 -63
  20. package/templates/workspace-root/skills/engagement-spec/SKILL.md +14 -0
  21. package/templates/workspace-root/skills/engagement-spec/references/spec-templates.md +4 -0
  22. package/templates/workspace-root/skills/house-voice/SKILL.md +172 -77
  23. package/templates/workspace-root/skills/ia-cli/SKILL.md +2 -1
  24. package/templates/workspace-root/skills/installagent-brand-kit/SKILL.md +8 -0
  25. package/templates/workspace-root/skills/installagent-brand-kit/references/branded-pdf.md +8 -1
  26. package/templates/workspace-root/skills/installagent-brand-kit/scripts/brand.py +32 -5
  27. package/templates/workspace-root/skills/slack-voice/SKILL.md +2 -2
  28. package/templates/workspace-root/skills/tech-call-prep/SKILL.md +7 -2
@@ -97,6 +97,49 @@ const PROJECT_ISSUES_QUERY = `
97
97
  }
98
98
  }
99
99
  `;
100
+ const PROJECT_ISSUE_STATES_QUERY = `
101
+ query ProjectIssueStates($projectId: ID!, $first: Int!, $after: String) {
102
+ issues(filter: { project: { id: { eq: $projectId } } }, first: $first, after: $after) {
103
+ nodes {
104
+ identifier
105
+ updatedAt
106
+ completedAt
107
+ state { type }
108
+ parent { identifier }
109
+ }
110
+ pageInfo { hasNextPage endCursor }
111
+ }
112
+ }
113
+ `;
114
+ /**
115
+ * Every issue in a project, open AND closed, as identifier + state + dates
116
+ * only (`client-drift`'s Linear mirror check). Strictly read-only: GraphQL
117
+ * queries, never mutations. Pages until done or `maxPages`.
118
+ */
119
+ export async function linearProjectIssueStates(fetchImpl, token, project, options = {}) {
120
+ const out = [];
121
+ let after = null;
122
+ for (let page = 0; page < (options.maxPages ?? 20); page++) {
123
+ const { issues, } = await linearRequest(fetchImpl, token, PROJECT_ISSUE_STATES_QUERY, {
124
+ projectId: project.id,
125
+ first: ISSUE_FETCH_PAGE_SIZE,
126
+ after,
127
+ });
128
+ for (const node of issues.nodes) {
129
+ out.push({
130
+ identifier: node.identifier,
131
+ stateType: node.state.type,
132
+ updatedAt: node.updatedAt,
133
+ completedAt: node.completedAt ?? null,
134
+ parent: node.parent?.identifier ?? null,
135
+ });
136
+ }
137
+ if (!issues.pageInfo.hasNextPage || !issues.pageInfo.endCursor)
138
+ break;
139
+ after = issues.pageInfo.endCursor;
140
+ }
141
+ return out;
142
+ }
100
143
  function toIssue(node) {
101
144
  return {
102
145
  identifier: node.identifier,
@@ -32,6 +32,18 @@ import { type GcpManifestKey } from "./client-manifest.js";
32
32
  * anywhere.
33
33
  */
34
34
  export declare const TEMPLATE_SYNCED_FILES: string[];
35
+ /**
36
+ * Client repos that left the template on purpose, with the reason. They are
37
+ * listed (so the report shows they were seen) but never compared and never
38
+ * written, not even by `--apply`. A shared rule change reaches them only by a
39
+ * hand copy, recorded in that repo's own commit.
40
+ *
41
+ * best-materials (2026-10-19): the repo moved to the client's GitHub org
42
+ * and dropped Linear. Its CADENCE.md (backlog, not Linear),
43
+ * lefthook.yml (runs every ci/*.test.mjs) and repo-lint CI are its own, and it
44
+ * has no PR → Slack workflow (the Install Agent org secrets are not there).
45
+ */
46
+ export declare const TEMPLATE_SYNC_EXCLUDED: Readonly<Record<string, string>>;
35
47
  export interface TemplateSyncOptions {
36
48
  /** The installagent/ workspace root (the dir that contains clients/). */
37
49
  workspaceDir: string;
@@ -50,6 +62,8 @@ export interface TemplateSyncRepoResult {
50
62
  dir: string;
51
63
  files: TemplateSyncFileResult[];
52
64
  inSync: boolean;
65
+ /** Set (with the reason) for a repo in TEMPLATE_SYNC_EXCLUDED: nothing was compared or written. */
66
+ excluded?: string;
53
67
  /**
54
68
  * CLIENT.md's Google Cloud keys (gcp_project / gcp_account) that are absent
55
69
  * or still the placeholder. Report only: CLIENT.md is per-client, so even
@@ -49,6 +49,14 @@ export const TEMPLATE_SYNCED_FILES = [
49
49
  // of CLIENT.md, the source of `ia portal sync-builds`.
50
50
  "ci/builds-manifest.mjs",
51
51
  "ci/builds-manifest.test.mjs",
52
+ // repo-lint also imports onboarding (rule 18): the generated status, news
53
+ // and Builds-card blocks of onboarding.html (client drift program, step 3).
54
+ "ci/onboarding.mjs",
55
+ "ci/onboarding.test.mjs",
56
+ // The one write command for every generated view (roadmap, progress list,
57
+ // onboarding blocks): rules 9, 10 and 18 name it, CADENCE.md points at it.
58
+ "ci/sync.mjs",
59
+ "ci/sync.test.mjs",
52
60
  "lefthook.yml",
53
61
  ".github/workflows/repo-lint.yml",
54
62
  ".github/workflows/pr-to-slack.yml",
@@ -57,6 +65,20 @@ export const TEMPLATE_SYNCED_FILES = [
57
65
  // in that repo's onboarding.html.
58
66
  "docs/kickoff-presentation.html",
59
67
  ];
68
+ /**
69
+ * Client repos that left the template on purpose, with the reason. They are
70
+ * listed (so the report shows they were seen) but never compared and never
71
+ * written, not even by `--apply`. A shared rule change reaches them only by a
72
+ * hand copy, recorded in that repo's own commit.
73
+ *
74
+ * best-materials (2026-10-19): the repo moved to the client's GitHub org
75
+ * and dropped Linear. Its CADENCE.md (backlog, not Linear),
76
+ * lefthook.yml (runs every ci/*.test.mjs) and repo-lint CI are its own, and it
77
+ * has no PR → Slack workflow (the Install Agent org secrets are not there).
78
+ */
79
+ export const TEMPLATE_SYNC_EXCLUDED = {
80
+ "best-materials": "diverged from the template on 2026-10-19 (client's GitHub org, no Linear): its CADENCE.md, lefthook.yml and CI are its own — copy a shared ci/ change by hand",
81
+ };
60
82
  /**
61
83
  * Compare (and optionally fix) the shared infra files every client-<slug>
62
84
  * build repo copies verbatim from client-template at creation time. Never
@@ -80,6 +102,11 @@ export async function templateSync(options) {
80
102
  const repos = [];
81
103
  for (const slug of slugs) {
82
104
  const dir = join(clientsDir, `client-${slug}`);
105
+ const excluded = TEMPLATE_SYNC_EXCLUDED[slug];
106
+ if (excluded) {
107
+ repos.push({ slug, dir, files: [], inSync: true, excluded, manifestGaps: [] });
108
+ continue;
109
+ }
83
110
  const fileResults = [];
84
111
  for (const rel of files) {
85
112
  const templateFile = join(templateDir, rel);
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@installagent/sdk",
3
- "version": "0.9.0",
3
+ "version": "0.10.0",
4
4
  "description": "Install Agent's shared SDK for internal team operations (client repos, n8n workflows, docs search, and more).",
5
5
  "type": "module",
6
6
  "main": "./dist/index.js",
@@ -34,6 +34,8 @@ installagent/
34
34
  ├── team-design/ # Install Agent design system source (tokens, components, guidelines)
35
35
  ├── team-branding/ # Logo files (static assets only)
36
36
  ├── skills/ # Cross-cutting agent skills (client deliverables pipeline, brand kit, …)
37
+ ├── team-tools/ # Internal technician tooling: the `ia` CLI, SDK, MCP server (see its AGENT.md)
38
+ ├── systems-department/ # Independent self-serve storefront repo (working name, unbranded) — own stack, no cross-imports
37
39
  ├── AGENT.md # ← you are here
38
40
  └── ONBOARDING.md # New-contractor orientation — read once, first
39
41
  ```
@@ -1,11 +1,13 @@
1
- # AGENTS.md
1
+ # AGENTS.md — installagent workspace root
2
2
 
3
- This repo's canonical agent instructions live in [`AGENT.md`](./AGENT.md).
4
- Read that file first.
3
+ Pointer file for agents that read `AGENTS.md` (Codex, Copilot, Aider,
4
+ Continue, and others). It holds no rules of its own.
5
5
 
6
- `AGENTS.md` exists so OpenAI Codex, ChatGPT desktop, and other tools that
7
- follow the [agents.md](https://agents.md) convention pick up the same rules.
8
- The contents are identical to `AGENT.md` — treat them as one document.
6
+ 1. Read [`AGENT.md`](./AGENT.md). It is the source of truth for the whole
7
+ workspace: layout, the "where to start a task" table, the golden rules,
8
+ and how the agentic files are layered.
9
+ 2. Read [`ONBOARDING.md`](./ONBOARDING.md) if you are landing here cold.
10
+ 3. Inside a repo, read that repo's `AGENT.md` (or `AGENTS.md`). It overrides
11
+ the root rules while you work there.
9
12
 
10
- If you're updating conventions, edit `AGENT.md`. Do not let these two files
11
- drift.
13
+ Do not add rule content to this file. Edit `AGENT.md` instead.
@@ -1,24 +1,12 @@
1
- # GEMINI.md
1
+ # GEMINI.md — installagent workspace root
2
2
 
3
- Instructions for the Gemini CLI agent (and other Google-powered agents)
4
- working at the root of this workspace.
3
+ Pointer file for the Gemini CLI and other Google-powered agents. It holds no
4
+ rules of its own.
5
5
 
6
- ## Read these first
6
+ 1. Read [`AGENT.md`](./AGENT.md). It is the source of truth for the whole
7
+ workspace.
8
+ 2. Read [`ONBOARDING.md`](./ONBOARDING.md) if you are landing here cold.
9
+ 3. Inside a repo, read that repo's `AGENT.md` (or `AGENTS.md`), then its
10
+ `GEMINI.md` if one exists (for example `team-web/apps/docs/GEMINI.md`).
7
11
 
8
- 1. [`AGENT.md`](./AGENT.md) — canonical conventions and rules. **This is the
9
- source of truth.**
10
- 2. [`README.md`](./README.md) — workspace overview.
11
- 3. The `AGENT.md` (or `AGENTS.md`) inside the repo you're working in:
12
- - [`clients/client-template/AGENT.md`](./clients/client-template/AGENT.md)
13
- - [`team-clients/AGENT.md`](./team-clients/AGENT.md)
14
- - [`team-infra/AGENT.md`](./team-infra/AGENT.md)
15
- - [`team-web/AGENT.md`](./team-web/AGENT.md)
16
-
17
- This root is a folder of independent git repos (`clients/client-*`,
18
- `team-*`); it is deliberately not a git repo itself. Each repo has its own
19
- conventions — always read the repo-level agentic file before editing inside it.
20
-
21
- ## Updating conventions
22
-
23
- Edit `AGENT.md` (root or repo) and any affected skills, not this file.
24
- This file is a pointer.
12
+ Do not add rule content to this file. Edit `AGENT.md` instead.
@@ -134,7 +134,9 @@ installagent/
134
134
  ├── team-web/ # installagent.com + team hub (Next.js pnpm workspace)
135
135
  ├── team-design/ # Install Agent design system source
136
136
  ├── team-branding/ # logo files
137
- └── skills/ # cross-cutting agent skills (client deliverables pipeline)
137
+ ├── skills/ # cross-cutting agent skills (client deliverables pipeline)
138
+ ├── team-tools/ # the `ia` CLI + SDK + MCP server for technicians
139
+ └── systems-department/ # independent self-serve storefront repo (unbranded working name)
138
140
  ```
139
141
 
140
142
  ## Orient yourself in this order
@@ -29,13 +29,13 @@ skills/
29
29
  ├── backtest-acceptance-gates/ # prove an automation works before the client trusts it (ground truth, evidence, gates)
30
30
  ├── installagent-brand-kit/ # our brand for print/PDF/Excalidraw/decks (logo + brand red #d11a1a)
31
31
  ├── design-system/ # the Install Agent Design System (screens/UI)
32
- ├── house-voice/ # house voice for client-facing writing + the ~150-word client message budget
32
+ ├── house-voice/ # house voice for client-facing writing; client messages are short by default (150 words = a flag, not a cap)
33
33
  ├── contract-tech-agnostic/ # contracts/SOWs by FUNCTION and OUTCOME, never tech (+ SOW template in references/)
34
34
  ├── linear/ # Linear issue workflow for client build work (status discipline, sub-issue trees, PR linking)
35
35
  ├── ia-cli/ # route internal ops through the `ia` CLI (team-tools) — decision map + guardrails
36
36
  ├── gcloud-cli-setup/ # one named gcloud configuration per account/client + check-before-you-run discipline
37
37
  ├── slack-voice/ # INTERNAL messages (Slack, email, chat): ~100 words, terse bullets, hard numbers (client → house-voice)
38
- ├── github-profile/ # force gh CLI + git commits onto the noahm-ia account before any GitHub action
38
+ ├── github-profile/ # force gh CLI + git commits onto the work account in root `.github-account` before any GitHub action
39
39
  └── init_repo/ # explicit-only /init_repo — dev branch + default branch + one milestone/root-branch per leaf issue
40
40
  ```
41
41
 
@@ -17,7 +17,7 @@ workflows, and diagrams across more than one repo. Repo-local skills live in
17
17
  ## How these get loaded
18
18
 
19
19
  Every skill is `<name>/SKILL.md` with YAML frontmatter (`name`, `description`).
20
- 23 of them are symlinked into [`../.claude/skills/`](../.claude/skills/), so Claude
20
+ 22 of them are symlinked into [`../.claude/skills/`](../.claude/skills/), so Claude
21
21
  Code and Cowork register them automatically — they appear in the skill menu and
22
22
  fire on their own without being invoked by name. The `description` is the
23
23
  trigger; the body is only read once the skill fires.
@@ -76,9 +76,17 @@ context, intake, agent bank, secrets, `wizard`/`doctor`). Check it before
76
76
  writing any custom script against GitHub, Airtable, Linear, Drive, n8n, or the
77
77
  portal.
78
78
 
79
- [`github-profile`](./github-profile/) — force gh CLI + git commits onto the
80
- `noahm-ia` account before any GitHub action on this machine (two accounts are
81
- logged in; only one is the work identity).
79
+ [`github-profile`](./github-profile/) — force gh CLI + git commits onto this
80
+ machine's work account before any GitHub action. The account comes from the
81
+ workspace-root `.github-account` file (two accounts are logged in; only one
82
+ is the work identity).
83
+
84
+ [`slack-voice`](./slack-voice/) — internal messages (Slack, email, chat):
85
+ terse, bulleted, hard numbers, about 100 words for an update. Client-facing
86
+ words stay with `house-voice`.
87
+
88
+ [`gcloud-cli-setup`](./gcloud-cli-setup/) — one named gcloud configuration
89
+ per account or client, and the check-before-you-run discipline.
82
90
 
83
91
  [`init_repo`](./init_repo/) — **explicit-invocation only**, never fires on
84
92
  its own. Run `/init_repo` against an existing `client-<slug>` repo to create
@@ -119,6 +119,9 @@ The onboarding checklist must **not feel overwhelming**. Rules:
119
119
  - **Measurable, hedged outcomes** — never guarantees.
120
120
  - **State the full commercial model** including the capped API-credit pass-through.
121
121
  - **No secrets / customer data / real VINs** in any doc.
122
+ - **No dates in the PDFs.** `brand.render_pdf` refuses them. Use "month one",
123
+ "week 4" or "at acceptance" in place of a calendar date. Pass
124
+ `allow_dates=True` only when the user explicitly asks for a date.
122
125
 
123
126
  ## Before you finish — checklist
124
127
 
@@ -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: 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) |
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
@@ -43,6 +43,18 @@ you keep that same build folder's `onboarding.html` in sync:
43
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. |
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
 
@@ -291,6 +303,8 @@ tokens or empty bullets.
291
303
  - [ ] `04-access-checklist.md`: §1 systems-only credentials table (every
292
304
  sales-call software has a row) + §2 decisions/information; Status set from
293
305
  what's actually confirmed (not assumed); §1 mirrored into the Access tab.
306
+ - [ ] Each of `01`–`04` has its Type line under the title:
307
+ `<!-- Type: spec -->` in `01` and `03`, `Type: spec` in `02` and `04`.
294
308
  - [ ] `onboarding.html`: no `REPLACE_WITH_*` tokens left unfilled (or, on an
295
309
  update pass, only the ones the tech-discovery call still hasn't
296
310
  answered); Client tab agrees with `02`, not the other way around.
@@ -10,6 +10,7 @@ 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
@@ -56,6 +57,7 @@ daily review queue that shrinks as the system learns."><br/>
56
57
 
57
58
  ```markdown
58
59
  # Tech Spec — <short system name>
60
+ Type: spec
59
61
 
60
62
  **Audience:** Install Agent engineering. Internal.
61
63
  **Status:** Pre-implementation, ready for build kickoff.
@@ -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.>
@@ -154,6 +157,7 @@ no access beyond the named systems.>
154
157
 
155
158
  ```markdown
156
159
  # Access & Credentials Checklist — <slug>
160
+ Type: spec
157
161
 
158
162
  Internal tracker: same items as `03-client-onboarding.md`'s §1 Access and §2
159
163
  Decisions, plus what we actually have. `03` is the **ask** we send the