@glasstrace/sdk 1.10.2 → 1.12.0

package/README.md

@@ -113,11 +113,49 @@ including composite invocations like `glasstrace init --yes --help`
 ## Refreshing agent instruction guidance
 
 `glasstrace init` and `glasstrace mcp add` write a managed Glasstrace
-MCP section into your project's agent instruction file (CLAUDE.md /
-codex.md / .cursorrules). The section opens with a cost-aware
-cross-tool decision paragraph telling your AI agent **when** Glasstrace
-MCP is worth calling and **which** tool is the cheapest first call for
-each symptom class.
+MCP section into your project's agent instruction file(s). Per the
+2026 cross-tool standard governed by the Agentic AI Foundation under
+the Linux Foundation (`agents.md`), the SDK writes:
+
+- **`AGENTS.md`** — universal cross-tool destination. Read by Cursor,
+  Codex, Claude Code, GitHub Copilot, Devin, Windsurf, and Gemini CLI.
+  Always written.
+- **`CLAUDE.md`** — Claude Code primary canonical destination.
+- **`GEMINI.md`** — Gemini CLI primary canonical destination (default
+  `context.fileName`).
+- **`.cursor/rules/glasstrace.mdc`** — Cursor canonical 2026
+  destination (Markdown-extension format with YAML frontmatter
+  `alwaysApply: true`); plus `.cursorrules` written unconditionally
+  as a transitional fallback for migration teams on mixed Cursor
+  versions.
+- **`.windsurf/rules/glasstrace.md`** — Windsurf workspace-rules
+  directory (active first-class format per Windsurf's docs at
+  `windsurf.com/university`).
+
+The section opens with explicit "Call Glasstrace FIRST when" / "SKIP
+Glasstrace when" decision rules telling your AI agent **when**
+Glasstrace MCP is worth calling and **which** tool is the cheapest
+first call for each symptom class.
+
+### Migration from legacy filenames
+
+If you installed `@glasstrace/sdk` before v1.11 (Wave 18 / DISC-1782),
+your project may have a managed Glasstrace block in legacy
+destinations the SDK no longer writes to as primary:
+
+- `codex.md` (Codex now reads `AGENTS.md` by default)
+- `.windsurfrules` (Windsurf moved to `.windsurf/rules/*.md`)
+
+Run `npx glasstrace upgrade-instructions` to migrate: the managed
+section is created at the new canonical destination(s). The legacy
+files are left untouched (their managed sections become stale but
+your free-text content is preserved); copy any custom prose from the
+legacy file to `AGENTS.md` to keep your agent's visibility into it.
+
+If you need to roll back to a pre-v1.11 SDK, pin to `~1.10.0` in
+`package.json`; the older SDK does not recognize `AGENTS.md` /
+`GEMINI.md` / `.cursor/rules/` as agent-instruction targets so its
+stale-section warning will not see them.
 
 The managed section's start marker carries an SDK version stamp, e.g.
 `<!-- glasstrace:mcp:start v=1.5.0 -->`. When you upgrade
@@ -488,9 +526,23 @@ operation kind (`email`, `calendar_link`, `webhook`, `external_api`,
 optional execution phase (`request`, `post_response`, `background`,
 `unknown`), and a small set of allowlisted semantic fields:
 `templateKey`, `providerOperation`, `role`, `locale`, `timezone`,
-`status`, `phase`. Each value is bounded to compact tokens — IANA
-timezones, BCP-47 locales, identifier-shaped enum tokens. The
-per-trace operation budget is five.
+`status`, `phase`, `recipientClass`, `participantCount`,
+`activeParticipantCount`. Each value is bounded to compact tokens —
+IANA timezones, BCP-47 locales, identifier-shaped enum tokens, or
+non-negative integer strings for the count fields. The per-span
+operation budget is five.
+
+`recipientClass`, `participantCount`, and `activeParticipantCount`
+let you record concise causal evidence about which recipient class
+was targeted and how many domain entities were included. The two
+count fields validate strictly as non-negative integer strings —
+`"0"`, `"1"`, `"12"` are accepted; `"-1"`, `"1.5"`, `"many"`, or
+any value with a non-digit character is rejected and counted under
+the `raw_payload` omission reason. `recipientClass` uses the
+identifier-shaped compact-token validator and preserves case
+verbatim, so normalize labels at the call site —
+`recipientClass="removed-participant"` (lowercase-kebab) is the
+recommended convention.
 
 What the SDK does not capture: recipient email addresses, sender or
 recipient names, rendered email subjects or bodies, calendar links,
@@ -526,6 +578,9 @@ recordSideEffect({
     role: "invitee",
     locale: "en-US",
     timezone: "Europe/Paris",
+    recipientClass: "removed-participant",
+    participantCount: "2",
+    activeParticipantCount: "1",
   },
 });
 ```