@dtmd/temper 0.0.10 → 0.0.12

package/dist/src/assembly.d.ts

@@ -29,11 +29,11 @@ export interface Admission {
     readonly admits: readonly KindDefinition<never>[];
 }
 /**
- * The declared enforcement-mode vocabulary — how firmly the `PreToolUse` guard
- * binds a tool call, split by where the finding goes.
- * `block`: denies the call.
- * `warn` (default): allows the call and surfaces the finding in-band, into the
- * live context. `note`: allows the call and records the finding out-of-band
+ * The declared enforcement-mode vocabulary — how firmly a guard binds an
+ * intercepted action, split by where the finding goes.
+ * `block`: denies the action.
+ * `warn` (default): allows the action and surfaces the finding in-band, into the
+ * live context. `note`: allows the action and records the finding out-of-band
  * only — the next report, never the session.
  */
 export type EnforcementMode = "note" | "warn" | "block";

package/dist/src/builtins.d.ts

@@ -300,6 +300,12 @@ export interface Hook {
     /** The tool-name filter a tool-scoped event fires on (`"*"`/`""`/absent = all). */
     readonly matcher?: string;
 }
+/**
+ * The manifest Claude Code's harness-level settings reside in — the file the assembly's
+ * residual settings keys fold into as opaque residue, the same manifest the `hook` kind's
+ * registrations surface inside (code.claude.com/docs/en/settings, retrieved 2026-07-16).
+ */
+export declare const SETTINGS_MANIFEST = "settings.json";
 /**
  * `hook` — a `settings.json` `hooks.<Event>` registration member: a fields-only kind (no
  * body slot), its members discovered off the `.claude/settings.json` manifest at the
@@ -569,11 +575,6 @@ export declare const pluginManifest: KindDefinition<PluginManifest>;
  *
  * Deliberately absent as undecidable: whether the `description` reads well, whether
  * `keywords` aid discovery, whether `name` names the pack aptly.
- *
- * Authoring notes the clauses cannot carry: leave `version` unset while iterating, so the
- * commit SHA drives updates and users are not stranded on a stale pin; set it once the
- * plugin has a release cycle, and bump it every time — pushing commits without bumping is
- * a no-op. Reach for `defaultEnabled: false` when the plugin costs money or scope on load.
  */
 export declare const pluginManifestDefaultContract: readonly Clause[];
 /**
@@ -713,14 +714,6 @@ export declare const marketplace: KindDefinition<Marketplace>;
  * there is no predicate that decides it, and a clause that guessed would fire on true
  * negatives. The enumerated deny list is the decidable subset; the impersonation rule rides
  * as guidance below.
- *
- * Authoring notes the clauses cannot carry: a relative-path `source` resolves against a
- * *local copy* of the marketplace, so it silently fails to resolve for users who added the
- * marketplace by direct URL to `marketplace.json` — only that one file is downloaded. Reach
- * for `github`, `url`, or `npm` when the catalog is distributed by URL. Where a git source
- * pins both `ref` and `sha`, the `sha` is the effective pin. A marketplace entry's
- * `defaultEnabled` beats the same field in the plugin's own `plugin.json`, while `version`
- * runs the other way — `plugin.json` wins.
  */
 export declare const marketplaceDefaultContract: readonly Clause[];
 /**
@@ -803,13 +796,6 @@ export declare const settingsLocalDefaultContract: readonly Clause[];
  * vagueness/no-op detection (semantic); gerund naming (judgment). Nothing
  * decidable is held: the name's hyphen placement and the platform's "no XML
  * tags in the description" are the two `shape` clauses below.
- *
- * Authoring notes the clauses cannot carry: prefer gerund or noun-phrase
- * names (`processing-pdfs`, `pdf-processing`) over vague ones (`helper`,
- * `utils`); `disable-model-invocation: true` for side-effectful workflows you
- * want to time yourself; `user-invocable: false` for background knowledge
- * that is not a command; `metadata` is the sanctioned home for versioning —
- * there is no top-level `version` field.
  */
 export declare const skillDefaultContract: readonly Clause[];
 /**
@@ -830,12 +816,16 @@ export declare const skillDefaultContract: readonly Clause[];
  */
 export declare const supportingDocDefaultContract: readonly Clause[];
 /**
- * The default contract for `command` — `skillDefaultContract`'s clauses minus `nameMatchesDir`: a
- * command is a lone file with no parent directory to match, so the one clause
- * that ranges over the directory relationship does not apply; every other
- * documented skill-schema recommendation, name-requiredness included, still
- * governs a command by the same import (code.claude.com/docs/en/skills,
- * retrieved 2026-07-15).
+ * The default contract for `command` — deliberately empty. A command is a lone
+ * markdown file whose frontmatter is entirely optional, matching the Claude Code
+ * runtime's documented flexibility. Where a skill requires `name` and
+ * `description` by the Agent Skills open standard, a command file may carry any,
+ * all, or none of them — identity comes from the filename stem, not a field
+ * (code.claude.com/docs/en/slash-commands, retrieved 2026-07-22).
+ *
+ * A command that passes here holds no contract constraint and loads everywhere
+ * the format is honored. The strictness stays with the skill kind, which enforces
+ * the portable profile for skill directories.
  */
 export declare const commandDefaultContract: readonly Clause[];
 /**
@@ -865,16 +855,6 @@ export declare const agentDefaultContract: readonly Clause[];
  * own: `required` is the one
  * presence predicate, and its absence is not itself a predicate.)
  * https://code.claude.com/docs/en/memory#path-specific-rules (retrieved 2026-07-15)
- *
- * What the clauses cannot carry, as guidance: keep a rule to facts Claude
- * should hold whenever the rule is in scope — concrete enough to verify ("use
- * 2-space indentation", not "format code properly"). If an entry is a
- * multi-step procedure or only matters occasionally, it belongs in a skill
- * (on-demand) rather than a rule (always-on). Prefer path-scoped rules when
- * one convention governs scattered paths; prefer per-directory CLAUDE.md when
- * directory owners maintain their own. Treat rules like code: prune them when
- * behavior drifts, and test a change by watching whether Claude's behavior
- * actually shifts.
  */
 export declare const ruleDefaultContract: readonly Clause[];
 /**
@@ -887,21 +867,6 @@ export declare const ruleDefaultContract: readonly Clause[];
  * schema to gate — manufacturing a required field or a forbidden-key list
  * would fake a check the format does not carry. The single clause is a context-cost
  * budget; everything else the contract could say is guidance.
- *
- * What the clauses cannot carry, as guidance: a `paths:` frontmatter block
- * belongs on a `.claude/rules/*.md` file, not on `CLAUDE.md` — the memory
- * docs document `paths` only for rules, so a rules-style header on
- * `CLAUDE.md` is dead configuration. Split a large file with `@path` imports
- * (resolved relative to the importing file, absolute allowed, recursion
- * capped at four hops; wrap a path in backticks to mention it without
- * importing). If the repo already ships an `AGENTS.md` for other agents,
- * don't duplicate it — create a `CLAUDE.md` that `@AGENTS.md`-imports it (or
- * symlink, except on Windows where the import is the recommended bridge).
- * Mind the loading asymmetry: every ancestor `CLAUDE.md` loads in full at
- * launch, while files in subdirectories load only when Claude reads a file
- * there — so a rule that must always hold belongs above the working
- * directory, not below it. Personal, un-shared notes go in `CLAUDE.local.md`
- * (gitignored), appended after `CLAUDE.md` at its level.
  */
 export declare const memoryAnthropicDefaultContract: readonly Clause[];
 /**
@@ -920,12 +885,29 @@ export declare const memoryAnthropicDefaultContract: readonly Clause[];
  * vocabulary's when/enumOf/type extensions, addressing still cannot spell a path into the
  * handler array (e.g., `hooks.<Event>[0].type`). A clause over it would range over a field
  * the read never surfaces, so it is no clause at all — the addressing-reach gap remains.
- * What the clauses cannot carry, as guidance: keep a handler's `type` among
- * `command`/`http`/`mcp_tool`/`prompt`/`agent`; a `command` handler needs a `command`, an
- * `http` handler a `url`; the `matcher` filters tool-scoped events and is inert on events
- * that carry no tool (`UserPromptSubmit`, `Stop`, and their siblings).
  */
 export declare const hookDefaultContract: readonly Clause[];
+/**
+ * The `settings.json` lifecycle event and matcher one documented telemetry event-name
+ * projects its tap hook at. The event-name is the author-facing token a telemetry
+ * verifier names (`contract.ts`'s `telemetry`, the `roster.rs` admissibility set); the
+ * `event` is the `hooks.<Event>` key the tap registers under, and the `matcher` scopes
+ * the fire to the telemetry-relevant subset — each an external fact
+ * (code.claude.com/docs/en/hooks, retrieved 2026-07-17):
+ *
+ * - `InstructionsLoaded` fires on a rule/memory load; its matcher filters the load
+ *   reason, and `path_glob_match` is the lazy per-path load the coverage tap reads.
+ * - `SkillInvoked` is a skill invocation, surfaced under `PostToolUse` with the tool-name
+ *   matcher `Skill` — the tap's own read of a skill call.
+ * - `UserPromptExpansion` fires on a command expansion; its matcher filters the command
+ *   name, `.*` capturing every one.
+ * - `ToolUse` fires after any tool call; its matcher filters the tool name, `.*`
+ *   capturing every one.
+ */
+export declare const TELEMETRY_EVENT_HOOKS: Readonly<Record<string, {
+    readonly event: string;
+    readonly matcher: string;
+}>>;
 /**
  * The default contract for `mcpServer` — Anthropic's documented `.mcp.json` contract
  * (code.claude.com/docs/en/mcp, retrieved 2026-07-15). A server surfaces at `mcpServers.*`,

package/dist/src/builtins.js

@@ -48,6 +48,7 @@ export const skill = kind({
     registration: [{ via: "user-invoked" }, { via: "description-trigger", field: "description" }],
     identityField: "name",
     templates: [{ kind: supportingDoc, path: "*.md" }],
+    guidance: "prefer gerund or noun-phrase names (`processing-pdfs`, `pdf-processing`) over vague ones (`helper`, `utils`); `disable-model-invocation: true` for side-effectful workflows you want to time yourself; `user-invocable: false` for background knowledge that is not a command; `metadata` is the sanctioned home for versioning — there is no top-level `version` field.",
 });
 /**
  * `command` — `.claude/commands/*.md`, the skill surface's legacy file placement
@@ -90,6 +91,7 @@ export const rule = kind({
     format: "yaml-frontmatter",
     unitShape: "file",
     registration: [{ via: "paths-match", field: "paths" }],
+    guidance: "keep a rule to facts Claude should hold whenever the rule is in scope — concrete enough to verify ('use 2-space indentation', not 'format code properly'). If an entry is a multi-step procedure or only matters occasionally, it belongs in a skill (on-demand) rather than a rule (always-on). Prefer path-scoped rules when one convention governs scattered paths; prefer per-directory CLAUDE.md when directory owners maintain their own. Treat rules like code: prune them when behavior drifts, and test a change by watching whether Claude's behavior actually shifts.",
 });
 /**
  * `memory` — a root `<name>.md` (`CLAUDE.md`, `AGENTS.md`), a lone file loaded
@@ -105,7 +107,14 @@ export const memory = kind({
     locus: { kind: "at", root: ".", glob: "**/CLAUDE.md" },
     unitShape: "file",
     registration: [{ via: "always" }],
+    guidance: "a `paths:` frontmatter block belongs on a `.claude/rules/*.md` file, not on `CLAUDE.md` — the memory docs document `paths` only for rules, so a rules-style header on `CLAUDE.md` is dead configuration. Split a large file with `@path` imports (resolved relative to the importing file, absolute allowed, recursion capped at four hops; wrap a path in backticks to mention it without importing). If the repo already ships an `AGENTS.md` for other agents, don't duplicate it — create a `CLAUDE.md` that `@AGENTS.md`-imports it (or symlink, except on Windows where the import is the recommended bridge). Mind the loading asymmetry: every ancestor `CLAUDE.md` loads in full at launch, while files in subdirectories load only when Claude reads a file there — so a rule that must always hold belongs above the working directory, not below it. Personal, un-shared notes go in `CLAUDE.local.md` (gitignored), appended after `CLAUDE.md` at its level.",
 });
+/**
+ * The manifest Claude Code's harness-level settings reside in — the file the assembly's
+ * residual settings keys fold into as opaque residue, the same manifest the `hook` kind's
+ * registrations surface inside (code.claude.com/docs/en/settings, retrieved 2026-07-16).
+ */
+export const SETTINGS_MANIFEST = "settings.json";
 /**
  * `hook` — a `settings.json` `hooks.<Event>` registration member: a fields-only kind (no
  * body slot), its members discovered off the `.claude/settings.json` manifest at the
@@ -115,11 +124,12 @@ export const memory = kind({
  */
 export const hook = kind({
     name: "hook",
-    locus: { kind: "at", root: ".claude", glob: "settings.json" },
+    locus: { kind: "at", root: ".claude", glob: SETTINGS_MANIFEST },
     unitShape: "file",
     registration: [{ via: "event", field: "event" }],
     shape: "fields",
-    collectionAddress: { manifest: "settings.json", keyPath: "hooks.<Event>", entryShape: "group-array(hooks;matcher)" },
+    collectionAddress: { manifest: SETTINGS_MANIFEST, keyPath: "hooks.<Event>", entryShape: "group-array(hooks;matcher)" },
+    guidance: "keep a handler's `type` among `command`/`http`/`mcp_tool`/`prompt`/`agent`; a `command` handler needs a `command`, an `http` handler a `url`; the `matcher` filters tool-scoped events and is inert on events that carry no tool (`UserPromptSubmit`, `Stop`, and their siblings).",
 });
 /**
  * `mcpServer` — a `.mcp.json` `mcpServers.*` registration member: a fields-only kind (no
@@ -147,11 +157,11 @@ export const mcpServer = kind({
  */
 export const installedPlugin = kind({
     name: "installed-plugin",
-    locus: { kind: "at", root: ".claude", glob: "settings.json" },
+    locus: { kind: "at", root: ".claude", glob: SETTINGS_MANIFEST },
     unitShape: "file",
     registration: [{ via: "enablement", field: "enabled" }],
     shape: "fields",
-    collectionAddress: { manifest: "settings.json", keyPath: "enabledPlugins.*", entryShape: "scalar(enabled)" },
+    collectionAddress: { manifest: SETTINGS_MANIFEST, keyPath: "enabledPlugins.*", entryShape: "scalar(enabled)" },
     // The marketplace half of the `<plugin>@<marketplace>` key is a declared edge to the
     // `known-marketplace` member it names (decision 0039). The half is not an authored field
     // — the engine splits it off the composite key at read (`src/kind.rs`, the read-time fold
@@ -190,11 +200,11 @@ export const installedPluginDefaultContract = [];
  */
 export const knownMarketplace = kind({
     name: "known-marketplace",
-    locus: { kind: "at", root: ".claude", glob: "settings.json" },
+    locus: { kind: "at", root: ".claude", glob: SETTINGS_MANIFEST },
     unitShape: "file",
     registration: [{ via: "registry" }],
     shape: "fields",
-    collectionAddress: { manifest: "settings.json", keyPath: "extraKnownMarketplaces.*", entryShape: "object" },
+    collectionAddress: { manifest: SETTINGS_MANIFEST, keyPath: "extraKnownMarketplaces.*", entryShape: "object" },
 });
 /**
  * The default contract for `known-marketplace` — **deliberately empty**. The format
@@ -222,6 +232,7 @@ export const pluginManifest = kind({
     unitShape: "named-field",
     registration: [],
     identityField: "name",
+    guidance: "leave `version` unset while iterating, so the commit SHA drives updates and users are not stranded on a stale pin; set it once the plugin has a release cycle, and bump it every time — pushing commits without bumping is a no-op. Reach for `defaultEnabled: false` when the plugin costs money or scope on load.",
 });
 /**
  * The default contract for `plugin-manifest` — the documented profile of `claude plugin
@@ -249,11 +260,6 @@ export const pluginManifest = kind({
  *
  * Deliberately absent as undecidable: whether the `description` reads well, whether
  * `keywords` aid discovery, whether `name` names the pack aptly.
- *
- * Authoring notes the clauses cannot carry: leave `version` unset while iterating, so the
- * commit SHA drives updates and users are not stranded on a stale pin; set it once the
- * plugin has a release cycle, and bump it every time — pushing commits without bumping is
- * a no-op. Reach for `defaultEnabled: false` when the plugin costs money or scope on load.
  */
 export const pluginManifestDefaultContract = [
     clause(required("name"), {
@@ -441,6 +447,7 @@ export const marketplace = kind({
     unitShape: "named-field",
     registration: [],
     identityField: "name",
+    guidance: "a relative-path `source` resolves against a *local copy* of the marketplace, so it silently fails to resolve for users who added the marketplace by direct URL to `marketplace.json` — only that one file is downloaded. Reach for `github`, `url`, or `npm` when the catalog is distributed by URL. Where a git source pins both `ref` and `sha`, the `sha` is the effective pin. A marketplace entry's `defaultEnabled` beats the same field in the plugin's own `plugin.json`, while `version` runs the other way — `plugin.json` wins.",
 });
 /**
  * The reserved marketplace names — reserved for official Anthropic use and refused to a
@@ -490,14 +497,6 @@ const RESERVED_MARKETPLACE_NAMES = [
  * there is no predicate that decides it, and a clause that guessed would fire on true
  * negatives. The enumerated deny list is the decidable subset; the impersonation rule rides
  * as guidance below.
- *
- * Authoring notes the clauses cannot carry: a relative-path `source` resolves against a
- * *local copy* of the marketplace, so it silently fails to resolve for users who added the
- * marketplace by direct URL to `marketplace.json` — only that one file is downloaded. Reach
- * for `github`, `url`, or `npm` when the catalog is distributed by URL. Where a git source
- * pins both `ref` and `sha`, the `sha` is the effective pin. A marketplace entry's
- * `defaultEnabled` beats the same field in the plugin's own `plugin.json`, while `version`
- * runs the other way — `plugin.json` wins.
  */
 export const marketplaceDefaultContract = [
     clause(required("name"), {
@@ -661,13 +660,6 @@ export const settingsLocalDefaultContract = [
  * vagueness/no-op detection (semantic); gerund naming (judgment). Nothing
  * decidable is held: the name's hyphen placement and the platform's "no XML
  * tags in the description" are the two `shape` clauses below.
- *
- * Authoring notes the clauses cannot carry: prefer gerund or noun-phrase
- * names (`processing-pdfs`, `pdf-processing`) over vague ones (`helper`,
- * `utils`); `disable-model-invocation: true` for side-effectful workflows you
- * want to time yourself; `user-invocable: false` for background knowledge
- * that is not a command; `metadata` is the sanctioned home for versioning —
- * there is no top-level `version` field.
  */
 export const skillDefaultContract = [
     clause(required("name"), {
@@ -770,14 +762,18 @@ export const supportingDocDefaultContract = [
     }),
 ];
 /**
- * The default contract for `command` — `skillDefaultContract`'s clauses minus `nameMatchesDir`: a
- * command is a lone file with no parent directory to match, so the one clause
- * that ranges over the directory relationship does not apply; every other
- * documented skill-schema recommendation, name-requiredness included, still
- * governs a command by the same import (code.claude.com/docs/en/skills,
- * retrieved 2026-07-15).
+ * The default contract for `command` — deliberately empty. A command is a lone
+ * markdown file whose frontmatter is entirely optional, matching the Claude Code
+ * runtime's documented flexibility. Where a skill requires `name` and
+ * `description` by the Agent Skills open standard, a command file may carry any,
+ * all, or none of them — identity comes from the filename stem, not a field
+ * (code.claude.com/docs/en/slash-commands, retrieved 2026-07-22).
+ *
+ * A command that passes here holds no contract constraint and loads everywhere
+ * the format is honored. The strictness stays with the skill kind, which enforces
+ * the portable profile for skill directories.
  */
-export const commandDefaultContract = skillDefaultContract.filter((entry) => entry.predicate.key !== "name-matches-dir");
+export const commandDefaultContract = [];
 /**
  * The default contract for `agent` — Anthropic's documented subagent contract
  * (code.claude.com/docs/en/sub-agents, retrieved 2026-07-15): `name` and
@@ -826,16 +822,6 @@ export const agentDefaultContract = [
  * own: `required` is the one
  * presence predicate, and its absence is not itself a predicate.)
  * https://code.claude.com/docs/en/memory#path-specific-rules (retrieved 2026-07-15)
- *
- * What the clauses cannot carry, as guidance: keep a rule to facts Claude
- * should hold whenever the rule is in scope — concrete enough to verify ("use
- * 2-space indentation", not "format code properly"). If an entry is a
- * multi-step procedure or only matters occasionally, it belongs in a skill
- * (on-demand) rather than a rule (always-on). Prefer path-scoped rules when
- * one convention governs scattered paths; prefer per-directory CLAUDE.md when
- * directory owners maintain their own. Treat rules like code: prune them when
- * behavior drifts, and test a change by watching whether Claude's behavior
- * actually shifts.
  */
 export const ruleDefaultContract = [
     clause(forbiddenKeys(["description", "globs", "alwaysApply"]), {
@@ -869,21 +855,6 @@ export const ruleDefaultContract = [
  * schema to gate — manufacturing a required field or a forbidden-key list
  * would fake a check the format does not carry. The single clause is a context-cost
  * budget; everything else the contract could say is guidance.
- *
- * What the clauses cannot carry, as guidance: a `paths:` frontmatter block
- * belongs on a `.claude/rules/*.md` file, not on `CLAUDE.md` — the memory
- * docs document `paths` only for rules, so a rules-style header on
- * `CLAUDE.md` is dead configuration. Split a large file with `@path` imports
- * (resolved relative to the importing file, absolute allowed, recursion
- * capped at four hops; wrap a path in backticks to mention it without
- * importing). If the repo already ships an `AGENTS.md` for other agents,
- * don't duplicate it — create a `CLAUDE.md` that `@AGENTS.md`-imports it (or
- * symlink, except on Windows where the import is the recommended bridge).
- * Mind the loading asymmetry: every ancestor `CLAUDE.md` loads in full at
- * launch, while files in subdirectories load only when Claude reads a file
- * there — so a rule that must always hold belongs above the working
- * directory, not below it. Personal, un-shared notes go in `CLAUDE.local.md`
- * (gitignored), appended after `CLAUDE.md` at its level.
  */
 export const memoryAnthropicDefaultContract = [
     clause(extent("lines", 200), {
@@ -947,10 +918,6 @@ const DOCUMENTED_HOOK_EVENTS = [
  * vocabulary's when/enumOf/type extensions, addressing still cannot spell a path into the
  * handler array (e.g., `hooks.<Event>[0].type`). A clause over it would range over a field
  * the read never surfaces, so it is no clause at all — the addressing-reach gap remains.
- * What the clauses cannot carry, as guidance: keep a handler's `type` among
- * `command`/`http`/`mcp_tool`/`prompt`/`agent`; a `command` handler needs a `command`, an
- * `http` handler a `url`; the `matcher` filters tool-scoped events and is inert on events
- * that carry no tool (`UserPromptSubmit`, `Stop`, and their siblings).
  */
 export const hookDefaultContract = [
     clause(enumOf("event", DOCUMENTED_HOOK_EVENTS), {
@@ -959,6 +926,29 @@ export const hookDefaultContract = [
         cite: "https://code.claude.com/docs/en/hooks (retrieved 2026-07-15)",
     }),
 ];
+/**
+ * The `settings.json` lifecycle event and matcher one documented telemetry event-name
+ * projects its tap hook at. The event-name is the author-facing token a telemetry
+ * verifier names (`contract.ts`'s `telemetry`, the `roster.rs` admissibility set); the
+ * `event` is the `hooks.<Event>` key the tap registers under, and the `matcher` scopes
+ * the fire to the telemetry-relevant subset — each an external fact
+ * (code.claude.com/docs/en/hooks, retrieved 2026-07-17):
+ *
+ * - `InstructionsLoaded` fires on a rule/memory load; its matcher filters the load
+ *   reason, and `path_glob_match` is the lazy per-path load the coverage tap reads.
+ * - `SkillInvoked` is a skill invocation, surfaced under `PostToolUse` with the tool-name
+ *   matcher `Skill` — the tap's own read of a skill call.
+ * - `UserPromptExpansion` fires on a command expansion; its matcher filters the command
+ *   name, `.*` capturing every one.
+ * - `ToolUse` fires after any tool call; its matcher filters the tool name, `.*`
+ *   capturing every one.
+ */
+export const TELEMETRY_EVENT_HOOKS = {
+    InstructionsLoaded: { event: "InstructionsLoaded", matcher: "path_glob_match" },
+    SkillInvoked: { event: "PostToolUse", matcher: "Skill" },
+    UserPromptExpansion: { event: "UserPromptExpansion", matcher: ".*" },
+    ToolUse: { event: "PostToolUse", matcher: ".*" },
+};
 /**
  * Every documented `.mcp.json` server transport — the closed set a server entry's `type`
  * is drawn from (code.claude.com/docs/en/mcp, retrieved 2026-07-15). `stdio` is the

package/dist/src/contract.d.ts

@@ -274,9 +274,8 @@ export declare const script: (path: string) => Verifier;
 /**
  * A telemetry verifier — the named documented harness events the emitted tap records
  * to a local-locus log, judged by reading the field record. Each name must be a
- * documented harness lifecycle event (`InstructionsLoaded`, `SkillInvoked`,
- * `UserPromptExpansion`, `ToolUse`; code.claude.com/docs/en/hooks, retrieved
- * 2026-07-17) — the gate checks each resolves, never records into it.
+ * documented harness lifecycle event — the gate checks each resolves, never records
+ * into it. See `TELEMETRY_EVENT_HOOKS` in `declarations.ts` for the vocabulary.
  */
 export declare const telemetry: (events: readonly string[]) => Verifier;
 /**

package/dist/src/contract.js

@@ -208,9 +208,8 @@ export const script = (path) => ({ species: "script", path });
 /**
  * A telemetry verifier — the named documented harness events the emitted tap records
  * to a local-locus log, judged by reading the field record. Each name must be a
- * documented harness lifecycle event (`InstructionsLoaded`, `SkillInvoked`,
- * `UserPromptExpansion`, `ToolUse`; code.claude.com/docs/en/hooks, retrieved
- * 2026-07-17) — the gate checks each resolves, never records into it.
+ * documented harness lifecycle event — the gate checks each resolves, never records
+ * into it. See `TELEMETRY_EVENT_HOOKS` in `declarations.ts` for the vocabulary.
  */
 export const telemetry = (events) => ({ species: "telemetry", events });
 /** An identity helper — types a requirement literal at the keystroke. */

package/dist/src/declarations.d.ts

@@ -9,7 +9,6 @@
  * in lockstep.
  */
 import type { Harness } from "./assembly.js";
-import type { MentionScope } from "./prose.js";
 import type { Declarations, Payload, RegistrationRow, SettingsRow } from "./generated/index.js";
 export type { AssemblyFactRow, ClauseRow, Declarations, KindFactRow, RequirementRow, SatisfiesRow, } from "./generated/index.js";
 /** The stable-sort ordering every declaration row family shares. */
@@ -56,6 +55,12 @@ export type RenderedExtents = ReadonlyMap<string, RenderedExtent>;
  * If a fields-only member declares no collection address — it surfaces in no host manifest.
  */
 export declare function registrationRows(harness: Harness): RegistrationRow[];
+/**
+ * Builds a collision-safe dedup key for a tap hook (event, matcher) pair.
+ * Two distinct pairs cannot produce the same key (e.g., ("Foo", "BarBaz") ≠ ("FooBar", "Baz")).
+ * @internal
+ */
+export declare function buildTapHookDedupeKey(event: string, matcher: string): string;
 /**
  * The synthesized tap-hook `registration` rows — one deduped `hooks.<Event>`
  * registration per (lifecycle event, matcher) any telemetry verifier names. Scans the
@@ -97,8 +102,6 @@ export declare function declaredAddresses(harness: Harness): Set<string>;
  * flat `kind:name` mention of one has no discovery locus to defer to.
  */
 export declare function declaredAtLocusKinds(harness: Harness): Set<string>;
-/** The full {@link MentionScope} the program resolves a mention against — its addresses and its deferral kinds. */
-export declare function mentionScope(harness: Harness): MentionScope;
 /**
  * Compile a harness into its seven declaration families — the erased program.
  *
@@ -110,8 +113,6 @@ export declare function mentionScope(harness: Harness): MentionScope;
  * or `extent` clause, so a whole compile goes through `emit`, never this alone.
  */
 export declare function compileDeclarations(harness: Harness, placements?: EdgePlacements, extents?: RenderedExtents): Declarations;
-/** The SDK's pinned engine/interchange version — the JSON pipe rides it in lockstep. */
-export declare const SEAM_VERSION = 2;
 /**
  * Serialize the seam payload to the internal versioned JSON pipe — `encodeSeam`
  * stamps `version`, so the caller supplies the rest of the {@link Payload}.

package/dist/src/declarations.js

@@ -10,6 +10,7 @@
  */
 import { fileURLToPath } from "node:url";
 import { isTextSpan, resolveLeaf } from "./prose.js";
+import { SETTINGS_MANIFEST, TELEMETRY_EVENT_HOOKS } from "./builtins.js";
 /**
  * Compile one `Clause` into its lock row: the shared `key`/`field`/`severity`/
  * `guidance`/`cite` columns — the clause's four channels surviving erasure
@@ -228,7 +229,7 @@ function collectionAddressRow(facts) {
  * the same spelling, absent for the committed default. `templates` names the embedded kinds the
  * corpus admits over it, and `content` lowers a declared layout (absent for a
  * `file`-content kind). A registration kind extends the row with its `shape` marker and
- * `collection_address`.
+ * `collection_address`. Advisory `guidance`/`cite` pair rides alongside (decision 0045).
  */
 function kindFactRow(facts, admissions) {
     if (facts.locus.kind === "embedded") {
@@ -250,6 +251,8 @@ function kindFactRow(facts, admissions) {
         content: contentRow(facts.content),
         shape: facts.shape,
         collection_address: collectionAddressRow(facts),
+        guidance: facts.guidance,
+        cite: facts.cite,
     };
 }
 /**
@@ -629,28 +632,13 @@ export function registrationRows(harness) {
  * (`src/tap.rs`). Every synthesized hook's `command` field carries it verbatim. */
 const TAP_COMMAND = "temper tap";
 /**
- * The `settings.json` lifecycle event and matcher one documented telemetry event-name
- * projects its tap hook at. The event-name is the author-facing token a telemetry
- * verifier names (`contract.ts`'s `telemetry`, the `roster.rs` admissibility set); the
- * `event` is the `hooks.<Event>` key the tap registers under, and the `matcher` scopes
- * the fire to the telemetry-relevant subset — each an external fact
- * (code.claude.com/docs/en/hooks, retrieved 2026-07-17):
- *
- * - `InstructionsLoaded` fires on a rule/memory load; its matcher filters the load
- *   reason, and `path_glob_match` is the lazy per-path load the coverage tap reads.
- * - `SkillInvoked` is a skill invocation, surfaced under `PostToolUse` with the tool-name
- *   matcher `Skill` — the tap's own read of a skill call.
- * - `UserPromptExpansion` fires on a command expansion; its matcher filters the command
- *   name, `.*` capturing every one.
- * - `ToolUse` fires after any tool call; its matcher filters the tool name, `.*`
- *   capturing every one.
+ * Builds a collision-safe dedup key for a tap hook (event, matcher) pair.
+ * Two distinct pairs cannot produce the same key (e.g., ("Foo", "BarBaz") ≠ ("FooBar", "Baz")).
+ * @internal
  */
-const TELEMETRY_EVENT_HOOKS = {
-    InstructionsLoaded: { event: "InstructionsLoaded", matcher: "path_glob_match" },
-    SkillInvoked: { event: "PostToolUse", matcher: "Skill" },
-    UserPromptExpansion: { event: "UserPromptExpansion", matcher: ".*" },
-    ToolUse: { event: "PostToolUse", matcher: ".*" },
-};
+export function buildTapHookDedupeKey(event, matcher) {
+    return JSON.stringify([event, matcher]);
+}
 /**
  * The synthesized tap-hook `registration` rows — one deduped `hooks.<Event>`
  * registration per (lifecycle event, matcher) any telemetry verifier names. Scans the
@@ -671,7 +659,7 @@ export function tapHookRows(harness) {
         for (const name of requirement.verifier.events) {
             const mapping = TELEMETRY_EVENT_HOOKS[name];
             if (mapping !== undefined)
-                deduped.set(`${mapping.event}${mapping.matcher}`, mapping);
+                deduped.set(buildTapHookDedupeKey(mapping.event, mapping.matcher), mapping);
         }
     };
     for (const requirement of Object.values(harness.require))
@@ -694,12 +682,6 @@ export function tapHookRows(harness) {
         ],
     }));
 }
-/**
- * The manifest Claude Code's harness-level settings reside in — the file the assembly's
- * residual settings keys fold into as opaque residue, the same manifest the `hook` kind's
- * registrations surface inside (code.claude.com/docs/en/settings, retrieved 2026-07-10).
- */
-const SETTINGS_MANIFEST = "settings.json";
 /**
  * The `settings` rows — the assembly's harness-level residual settings keys, each folded
  * into the settings.json manifest's opaque residue at emit. Key-sorted so double emit is
@@ -757,7 +739,7 @@ export function declaredAtLocusKinds(harness) {
     return new Set(atLocusKindsInPlay(kindsInPlay(harness)).map((facts) => facts.name));
 }
 /** The full {@link MentionScope} the program resolves a mention against — its addresses and its deferral kinds. */
-export function mentionScope(harness) {
+function mentionScope(harness) {
     return { mentionable: declaredAddresses(harness), deferrableKinds: declaredAtLocusKinds(harness) };
 }
 /**
@@ -793,7 +775,7 @@ export function compileDeclarations(harness, placements, extents) {
     };
 }
 /** The SDK's pinned engine/interchange version — the JSON pipe rides it in lockstep. */
-export const SEAM_VERSION = 2;
+const SEAM_VERSION = 2;
 /**
  * Serialize the seam payload to the internal versioned JSON pipe — `encodeSeam`
  * stamps `version`, so the caller supplies the rest of the {@link Payload}.

package/dist/src/emit.d.ts

@@ -10,7 +10,7 @@
  */
 import type { Harness } from "./assembly.js";
 import type { Member } from "./kind.js";
-import type { Declarations, RenderedExtent } from "./declarations.js";
+import type { Declarations } from "./declarations.js";
 import type { PayloadMember } from "./generated/index.js";
 export type { PayloadMember } from "./generated/index.js";
 /** What a mention may resolve against at emit. */
@@ -30,27 +30,6 @@ export interface ResolveOptions {
      */
     readonly members?: ReadonlyMap<string, Member>;
 }
-/**
- * Every composed embedded value's placed edge fields, keyed by the value's
- * {@link placementKey} — what `emit` hands {@link compileDeclarations} so each
- * `nested_member` row carries its own format's placement record. Iterates exactly the
- * values `nestedMemberRows` does, so every edge-bearing row it builds has an observation.
- */
-export declare function edgePlacements(harness: Harness, options: ResolveOptions): Map<string, string[]>;
-/**
- * Every composed embedded value's rendered extent — the line and character count of the
- * block `emit` projected for it — keyed by its {@link placementKey}, what `emit` hands
- * {@link compileDeclarations} so each `nested_member` row carries the span an `extent`
- * clause budgets. Iterates exactly the values {@link edgePlacements} does, rendering each
- * through the same {@link renderMemberBlock} the body projection uses (a hook is pure, so
- * the measured render and the projected one cannot disagree), never a second renderer.
- *
- * A value the SDK composes is always rendered here, so it always captures a span; a value
- * no format rendered — an embedded member read off a layout host's source — is lowered by
- * the engine, not this pass, and reaches its row with no span (the `placed_edges`
- * distinction between an observed empty and an unobserved absence).
- */
-export declare function renderedExtents(harness: Harness, options: ResolveOptions): Map<string, RenderedExtent>;
 /**
  * One fields-only registration member erased for the manifest write face: its key
  * (a hook's lifecycle event, an MCP server's name), the collection address it keys

package/dist/src/emit.js

@@ -348,7 +348,7 @@ function placedEdges(host, value, options) {
  * `nested_member` row carries its own format's placement record. Iterates exactly the
  * values `nestedMemberRows` does, so every edge-bearing row it builds has an observation.
  */
-export function edgePlacements(harness, options) {
+function edgePlacements(harness, options) {
     const placements = new Map();
     for (const member of harness.members) {
         if (member.prose?.kind !== "blocks")
@@ -389,7 +389,7 @@ function renderedLineCount(block) {
  * the engine, not this pass, and reaches its row with no span (the `placed_edges`
  * distinction between an observed empty and an unobserved absence).
  */
-export function renderedExtents(harness, options) {
+function renderedExtents(harness, options) {
     const extents = new Map();
     for (const member of harness.members) {
         if (member.prose?.kind !== "blocks")

package/dist/src/generated/KindFactRow.d.ts

@@ -79,4 +79,13 @@ export type KindFactRow = {
      * file-locus kind, so an ordinary row stays byte-identical.
      */
     collection_address?: CollectionAddressRow;
+    /**
+     * Advisory authoring counsel for the kind as a whole — teaching at authoring time via
+     * `schema` hover or `explain`, carrying no predicate or severity (decision 0045).
+     */
+    guidance?: string;
+    /**
+     * External-fact source backing the guidance — a doc URL plus retrieved date.
+     */
+    cite?: string;
 };

package/dist/src/kind.d.ts

@@ -210,6 +210,12 @@ export interface KindFacts {
     /** Fact 7, template — one {@link Template} per inner layer of nested members the kind
      * hosts; absent for a kind that nests nothing. */
     readonly templates?: readonly Template[];
+    /** Advisory authoring counsel for the kind as a whole — teaching at authoring time via
+     * `schema` hover or `explain`, carrying no predicate or severity (decision 0045). */
+    readonly guidance?: string;
+    /** External-fact source backing the guidance — a doc URL plus retrieved date,
+     * carried as data. */
+    readonly cite?: string;
 }
 /**
  * One authored member — a typed value in the library. Kind identity travels by

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dtmd/temper",
-  "version": "0.0.10",
+  "version": "0.0.12",
   "description": "The temper authoring face — the six-noun model as typed modules: harness(), kind<T>(), clause values, needs, and file()/text/blocks(). Emit compiles to the declaration rows the engine reads, a byte-faithful projection, and the lock.",
   "license": "(MIT OR Apache-2.0)",
   "repository": {
@@ -52,7 +52,7 @@
     "temper": "bin/temper.js"
   },
   "optionalDependencies": {
-    "@dtmd/temper-linux-x64": "0.0.10",
-    "@dtmd/temper-win32-x64": "0.0.10"
+    "@dtmd/temper-linux-x64": "0.0.12",
+    "@dtmd/temper-win32-x64": "0.0.12"
   }
 }