@havesomecode/kibana-mcp-server 0.1.0

package/dist/src/tools/discover.js

@@ -0,0 +1,47 @@
+import { z } from "zod";
+export const discoverInputSchema = z.object({
+    query: z.string().trim().min(1).optional(),
+    limit: z.number().int().positive().max(100).default(20),
+});
+export const discoverOutputSchema = z.object({
+    total: z.number().int().nonnegative(),
+    sources: z.array(z.object({
+        id: z.string(),
+        name: z.string(),
+        description: z.string().optional(),
+        tags: z.array(z.string()),
+        time_field: z.string(),
+        field_hints: z.array(z.object({
+            name: z.string(),
+            type: z.string().optional(),
+            description: z.string().optional(),
+            aliases: z.array(z.string()),
+        })),
+    })),
+});
+export function executeDiscover(input, sourceCatalog) {
+    const sources = sourceCatalog.list(input.query, input.limit);
+    return {
+        total: sources.length,
+        sources,
+    };
+}
+export function formatDiscoverResult(result) {
+    if (result.sources.length === 0) {
+        return "No sources matched the requested discovery query.";
+    }
+    return result.sources
+        .map((source) => {
+        const fieldPreview = source.field_hints.length > 0
+            ? source.field_hints.map((fieldHint) => fieldHint.name).join(", ")
+            : "no field hints configured";
+        return `${source.id}: ${source.name} [${source.tags.join(", ")}] time_field=${source.time_field} fields=${fieldPreview}`;
+    })
+        .join("\n");
+}
+export function createDiscoverCallToolResult(result) {
+    return {
+        content: [{ type: "text", text: formatDiscoverResult(result) }],
+        structuredContent: result,
+    };
+}

package/dist/src/tools/filter.js

@@ -0,0 +1,141 @@
+import { z } from "zod";
+import { executeQuery, queryOutputSchema } from "./query.js";
+const exactFilterSchema = z.object({
+    field: z.string().min(1),
+    value: z.union([z.string(), z.number(), z.boolean()]),
+});
+const nestedExactFilterSchema = z.object({
+    path: z.string().min(1),
+    field: z.string().min(1),
+    value: z.union([z.string(), z.number(), z.boolean()]),
+});
+export const filterInputSchema = z
+    .object({
+    source_ids: z.array(z.string().min(1)).min(1),
+    start_time: z.string().datetime({ offset: true }),
+    end_time: z.string().datetime({ offset: true }),
+    field: z.string().min(1),
+    value: z.union([z.string(), z.number(), z.boolean()]),
+    filters: z.array(exactFilterSchema).default([]),
+    nested_filters: z.array(nestedExactFilterSchema).default([]),
+    cursor: z.string().min(1).optional(),
+    mode: z
+        .enum(["hits", "count", "histogram", "terms", "stats", "grouped_top_hits"])
+        .default("hits"),
+    sort: z.enum(["asc", "desc"]).default("desc"),
+    sort_by: z.string().min(1).optional(),
+    limit: z.number().int().positive().max(1000).default(100),
+    extract_nested: z.boolean().default(false),
+    stats_field: z.string().min(1).optional(),
+    top_hits_size: z.number().int().positive().max(100).default(1),
+    histogram_interval: z.string().min(1).optional(),
+    group_by: z.string().min(1).optional(),
+})
+    .superRefine((value, ctx) => {
+    if (Date.parse(value.start_time) >= Date.parse(value.end_time)) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ["end_time"],
+            message: "end_time must be later than start_time",
+        });
+    }
+    if (value.mode === "histogram" && !value.histogram_interval) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ["histogram_interval"],
+            message: "histogram_interval is required when mode is 'histogram'",
+        });
+    }
+    if ((value.mode === "terms" || value.mode === "grouped_top_hits") && !value.group_by) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ["group_by"],
+            message: `group_by is required when mode is '${value.mode}'`,
+        });
+    }
+    if (!["hits", "grouped_top_hits"].includes(value.mode) && value.sort_by) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ["sort_by"],
+            message: "sort_by is only supported when mode is 'hits' or 'grouped_top_hits'",
+        });
+    }
+    if (value.cursor && value.mode !== "hits") {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ["cursor"],
+            message: "cursor is only supported when mode is 'hits'",
+        });
+    }
+    if (value.cursor && value.source_ids.length !== 1) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ["cursor"],
+            message: "cursor pagination is only supported for single-source hits queries",
+        });
+    }
+    if (value.mode === "stats" && !value.stats_field) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ["stats_field"],
+            message: "stats_field is required when mode is 'stats'",
+        });
+    }
+    if (value.mode === "grouped_top_hits" && !value.sort_by) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ["sort_by"],
+            message: "sort_by is required when mode is 'grouped_top_hits'",
+        });
+    }
+});
+export const filterOutputSchema = queryOutputSchema;
+export async function executeFilter(input, sourceCatalog, kibanaClient, options) {
+    return executeQuery({
+        source_ids: input.source_ids,
+        start_time: input.start_time,
+        end_time: input.end_time,
+        filters: [{ field: input.field, value: input.value }, ...input.filters],
+        nested_filters: input.nested_filters,
+        cursor: input.cursor,
+        mode: input.mode,
+        sort: input.sort,
+        sort_by: input.sort_by,
+        limit: input.limit,
+        extract_nested: input.extract_nested,
+        stats_field: input.stats_field,
+        top_hits_size: input.top_hits_size,
+        histogram_interval: input.histogram_interval,
+        group_by: input.group_by,
+    }, sourceCatalog, kibanaClient, {
+        resolveFieldAliases: false,
+        resolvePreferredExactFields: true,
+        schemaCatalog: options?.schemaCatalog,
+    });
+}
+export function formatFilterResult(result) {
+    if (result.hits) {
+        const preview = result.hits
+            .slice(0, 5)
+            .map((hit) => `[${hit.timestamp ?? "no-timestamp"}] ${hit.source_id}: ${hit.summary}`)
+            .join("\n");
+        return `Returned ${result.hits.length} exact-field matches (total=${result.total}).\n${preview}`;
+    }
+    if (result.counts_by_source) {
+        return result.counts_by_source.map((count) => `${count.source_id}: ${count.count}`).join("\n");
+    }
+    if (result.histograms) {
+        return result.histograms
+            .map((histogram) => `${histogram.source_id}: ${histogram.buckets.length} histogram buckets`)
+            .join("\n");
+    }
+    return (result.groups ?? [])
+        .map((group) => `${group.source_id} grouped by ${group.field}: ${group.buckets.length} buckets`)
+        .join("\n");
+}
+export function createFilterCallToolResult(result) {
+    return {
+        content: [{ type: "text", text: formatFilterResult(result) }],
+        structuredContent: result,
+    };
+}

package/dist/src/tools/query.js

@@ -0,0 +1,287 @@
+import { z } from "zod";
+import { compileQueryPlan } from "../query/compiler.js";
+import { normalizeQueryResponse } from "../query/normalize.js";
+const queryFilterSchema = z.object({
+    field: z.string().min(1),
+    value: z.union([z.string(), z.number(), z.boolean()]),
+});
+const nestedQueryFilterSchema = z.object({
+    path: z.string().min(1),
+    field: z.string().min(1),
+    value: z.union([z.string(), z.number(), z.boolean()]),
+});
+export const queryInputSchema = z
+    .object({
+    source_ids: z.array(z.string().min(1)).min(1),
+    start_time: z.string().datetime({ offset: true }),
+    end_time: z.string().datetime({ offset: true }),
+    text: z.string().trim().min(1).optional(),
+    filters: z.array(queryFilterSchema).default([]),
+    nested_filters: z.array(nestedQueryFilterSchema).default([]),
+    cursor: z.string().min(1).optional(),
+    mode: z
+        .enum(["hits", "count", "histogram", "terms", "stats", "grouped_top_hits"])
+        .default("hits"),
+    sort: z.enum(["asc", "desc"]).default("desc"),
+    sort_by: z.string().min(1).optional(),
+    limit: z.number().int().positive().max(1000).default(100),
+    extract_nested: z.boolean().default(false),
+    stats_field: z.string().min(1).optional(),
+    top_hits_size: z.number().int().positive().max(100).default(1),
+    histogram_interval: z.string().min(1).optional(),
+    group_by: z.string().min(1).optional(),
+})
+    .superRefine((value, ctx) => {
+    if (Date.parse(value.start_time) >= Date.parse(value.end_time)) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ["end_time"],
+            message: "end_time must be later than start_time",
+        });
+    }
+    if (value.mode === "histogram" && !value.histogram_interval) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ["histogram_interval"],
+            message: "histogram_interval is required when mode is 'histogram'",
+        });
+    }
+    if ((value.mode === "terms" || value.mode === "grouped_top_hits") && !value.group_by) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ["group_by"],
+            message: `group_by is required when mode is '${value.mode}'`,
+        });
+    }
+    if (!["hits", "grouped_top_hits"].includes(value.mode) && value.sort_by) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ["sort_by"],
+            message: "sort_by is only supported when mode is 'hits' or 'grouped_top_hits'",
+        });
+    }
+    if (value.cursor && value.mode !== "hits") {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ["cursor"],
+            message: "cursor is only supported when mode is 'hits'",
+        });
+    }
+    if (value.cursor && value.source_ids.length !== 1) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ["cursor"],
+            message: "cursor pagination is only supported for single-source hits queries",
+        });
+    }
+    if (value.mode === "stats" && !value.stats_field) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ["stats_field"],
+            message: "stats_field is required when mode is 'stats'",
+        });
+    }
+    if (value.mode === "grouped_top_hits" && !value.sort_by) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ["sort_by"],
+            message: "sort_by is required when mode is 'grouped_top_hits'",
+        });
+    }
+});
+export const queryOutputSchema = z.object({
+    query_echo: z.object({
+        source_ids: z.array(z.string()),
+        start_time: z.string(),
+        end_time: z.string(),
+        text: z.string().optional(),
+        filters: z.array(z.object({
+            field: z.string(),
+            value: z.union([z.string(), z.number(), z.boolean()]),
+            resolved_field: z.string(),
+        })),
+        nested_filters: z
+            .array(z.object({
+            path: z.string(),
+            field: z.string(),
+            value: z.union([z.string(), z.number(), z.boolean()]),
+            resolved_field: z.string(),
+            query_strategy: z.enum(["nested", "flat_object_path"]).optional(),
+        }))
+            .optional(),
+        cursor: z.string().optional(),
+        mode: z.enum(["hits", "count", "histogram", "terms", "stats", "grouped_top_hits"]),
+        sort: z.enum(["asc", "desc"]),
+        sort_by: z.string().optional(),
+        resolved_sort_by_by_source: z
+            .array(z.object({
+            source_id: z.string(),
+            resolved_sort_by: z.string(),
+        }))
+            .optional(),
+        advisories: z
+            .array(z.object({
+            kind: z.enum(["preferred_exact_field", "schema_unavailable", "non_nested_object_array"]),
+            source_id: z.string(),
+            purpose: z.enum(["filter", "sort", "group_by"]),
+            requested_field: z.string(),
+            resolved_field: z.string(),
+            reason: z.string(),
+        }))
+            .optional(),
+        limit: z.number(),
+        stats_field: z.string().optional(),
+        top_hits_size: z.number().optional(),
+        histogram_interval: z.string().optional(),
+        group_by: z.string().optional(),
+        truncated: z.boolean(),
+    }),
+    total: z.number(),
+    next_cursor: z.string().optional(),
+    hits: z
+        .array(z.object({
+        source_id: z.string(),
+        timestamp: z.string().nullable(),
+        summary: z.string(),
+        document_id: z.string().nullable(),
+        index: z.string().nullable(),
+        selected_fields: z.record(z.string(), z.unknown()),
+        nested_matches: z
+            .array(z.object({
+            path: z.string(),
+            documents: z.array(z.record(z.string(), z.unknown())),
+        }))
+            .optional(),
+        raw_document: z.record(z.string(), z.unknown()),
+    }))
+        .optional(),
+    counts_by_source: z
+        .array(z.object({
+        source_id: z.string(),
+        count: z.number(),
+    }))
+        .optional(),
+    histograms: z
+        .array(z.object({
+        source_id: z.string(),
+        buckets: z.array(z.object({
+            key: z.union([z.number(), z.string()]),
+            key_as_string: z.string().optional(),
+            count: z.number(),
+        })),
+    }))
+        .optional(),
+    groups: z
+        .array(z.object({
+        source_id: z.string(),
+        field: z.string(),
+        buckets: z.array(z.object({
+            key: z.string(),
+            count: z.number(),
+        })),
+    }))
+        .optional(),
+    stats: z
+        .array(z.object({
+        source_id: z.string(),
+        field: z.string(),
+        summary: z.object({
+            count: z.number(),
+            min: z.number().nullable(),
+            max: z.number().nullable(),
+            avg: z.number().nullable(),
+            sum: z.number(),
+            p50: z.number().nullable(),
+            p95: z.number().nullable(),
+            p99: z.number().nullable(),
+        }),
+    }))
+        .optional(),
+    grouped_hits: z
+        .array(z.object({
+        source_id: z.string(),
+        group_by: z.string(),
+        buckets: z.array(z.object({
+            key: z.string(),
+            count: z.number(),
+            hits: z.array(z.object({
+                source_id: z.string(),
+                timestamp: z.string().nullable(),
+                summary: z.string(),
+                document_id: z.string().nullable(),
+                index: z.string().nullable(),
+                selected_fields: z.record(z.string(), z.unknown()),
+                nested_matches: z
+                    .array(z.object({
+                    path: z.string(),
+                    documents: z.array(z.record(z.string(), z.unknown())),
+                }))
+                    .optional(),
+                raw_document: z.record(z.string(), z.unknown()),
+            })),
+        })),
+    }))
+        .optional(),
+});
+export async function executeQuery(input, sourceCatalog, kibanaClient, options) {
+    const sources = sourceCatalog.getRequiredSources(input.source_ids);
+    const schemaCatalog = options?.schemaCatalog;
+    const usesSchemaAwareFieldResolution = (options?.resolveFieldAliases !== false || options?.resolvePreferredExactFields !== false) &&
+        (input.filters.length > 0 || Boolean(input.sort_by) || Boolean(input.group_by));
+    const needsSchemaResolution = usesSchemaAwareFieldResolution || input.nested_filters.length > 0;
+    const sourceSchemas = new Map();
+    const sourceSchemaErrors = new Map();
+    if (schemaCatalog && needsSchemaResolution) {
+        for (const source of sources) {
+            try {
+                sourceSchemas.set(source.id, await schemaCatalog.getFields(source));
+            }
+            catch (error) {
+                sourceSchemaErrors.set(source.id, error instanceof Error ? error.message : String(error));
+            }
+        }
+    }
+    const plan = compileQueryPlan(input, sources, {
+        ...options,
+        ...(sourceSchemas.size > 0 ? { sourceSchemas } : {}),
+        ...(sourceSchemaErrors.size > 0 ? { sourceSchemaErrors } : {}),
+    });
+    const executions = await kibanaClient.executeMany(plan.sourceQueries);
+    return queryOutputSchema.parse(normalizeQueryResponse(plan, executions));
+}
+export function formatQueryResult(result) {
+    if (result.hits) {
+        const preview = result.hits
+            .slice(0, 5)
+            .map((hit) => `[${hit.timestamp ?? "no-timestamp"}] ${hit.source_id}: ${hit.summary}`)
+            .join("\n");
+        return `Returned ${result.hits.length} hits (total=${result.total}).\n${preview}`;
+    }
+    if (result.counts_by_source) {
+        return result.counts_by_source.map((count) => `${count.source_id}: ${count.count}`).join("\n");
+    }
+    if (result.histograms) {
+        return result.histograms
+            .map((histogram) => `${histogram.source_id}: ${histogram.buckets.length} histogram buckets`)
+            .join("\n");
+    }
+    if (result.stats) {
+        return result.stats
+            .map((entry) => `${entry.source_id} ${entry.field}: p95=${entry.summary.p95 ?? "n/a"}`)
+            .join("\n");
+    }
+    if (result.grouped_hits) {
+        return result.grouped_hits
+            .map((entry) => `${entry.source_id} grouped top hits: ${entry.buckets.length} buckets`)
+            .join("\n");
+    }
+    return (result.groups ?? [])
+        .map((group) => `${group.source_id} grouped by ${group.field}: ${group.buckets.length} buckets`)
+        .join("\n");
+}
+export function createQueryCallToolResult(result) {
+    return {
+        content: [{ type: "text", text: formatQueryResult(result) }],
+        structuredContent: result,
+    };
+}

package/dist/src/types.js

@@ -0,0 +1 @@
+export {};

package/docs/project/compatibility-matrix.md

@@ -0,0 +1,22 @@
+---
+title: Compatibility Matrix
+status: active
+updated: 2026-04-06
+---
+
+# Compatibility Matrix
+
+This matrix distinguishes guaranteed support from best-effort behavior. Each claim includes an evidence basis so readers know what is tested vs inferred.
+
+| Area | Status | Evidence basis | Notes |
+| --- | --- | --- | --- |
+| Node.js 22+ runtime | Guaranteed | Verified in CI via `.node-version` | Required for build and runtime. |
+| Repo-local Codex plugin install | Guaranteed | Verified via `npm run verify` and entrypoint checks | Requires `npm install` + `npm run build`. |
+| Fully autonomous plugin install by prompting alone across Codex model variants | Best-effort | Field reports show model-dependent behavior | Manual install from the local marketplace is the supported fallback when the agent cannot complete the UI step itself. |
+| `kibana_internal_search_es` backend | Guaranteed | Verified in tests | Primary search transport. |
+| `elasticsearch_search` backend | Guaranteed | Verified in tests | Direct Elasticsearch-compatible search path. |
+| Schema metadata endpoints | Best-effort | Known 404s in some deployments | `describe_fields` may fail if endpoints are blocked. |
+| Nested query features | Best-effort | Depends on schema availability | Requires schema metadata for validation. |
+| Public package install | Planned | Not yet verified | Enabled after artifact verification and release automation. |
+
+Upgrade a row from best-effort to guaranteed only after verifying it in CI or in a reproducible environment test and documenting the evidence here.

package/docs/project/distribution-strategy.md

@@ -0,0 +1,78 @@
+---
+title: Distribution Strategy
+status: active
+updated: 2026-04-09
+---
+
+# Distribution Strategy
+
+## Goals
+
+- Make the MCP installable by AI agents without manual explanation.
+- Preserve the repo-local Codex plugin workflow as the guaranteed path.
+- Offer a public distribution path once the artifact boundary is verified.
+
+## Supported Distribution Paths
+
+### 1. Repo-local Codex plugin (guaranteed)
+
+This is the primary, always-supported path:
+
+1. Clone the repo.
+2. `npm install`
+3. `npm run build`
+4. Install the `Kibana Log Investigation` plugin from the repo marketplace in Codex.
+
+This path is required for development and is the baseline for support.
+
+### 2. Public package (planned, gated)
+
+The package surface is prepared for agent-friendly execution via:
+
+- `npx -y @havesomecode/kibana-mcp-server`
+- MCP clients that invoke the published package binary instead of a repo-local build
+
+Public publishing remains gated until the following are complete:
+
+- npm package ownership is under maintainer control for the chosen package name
+- Verified `npm pack` contents (runtime entrypoint, plugin metadata, README, LICENSE).
+- CI and release workflows green on the supported Node line.
+- Clear support policy and compatibility matrix published.
+- Trusted publishing enabled (OIDC), no long-lived publish tokens.
+
+This path is optional until explicitly enabled.
+
+## Artifact Boundary
+
+The release artifact must include:
+
+- `dist/` runtime build output
+- plugin metadata and MCP config
+- `README.md`, `LICENSE`
+
+The release artifact must exclude:
+
+- tests and fixtures
+- local operator config (`config/sources.json`, `config/sources.runtime.json`)
+- development-only scripts and tooling that do not affect runtime execution
+
+## Versioning
+
+Releases use semantic versioning driven by `semantic-release`.
+
+The authoritative release record is:
+
+- Git tags
+- npm package versions
+- GitHub Releases
+
+The repository does not commit generated version bumps or release notes back into git.
+
+## Decision Triggers
+
+Move from repo-local only to public publishing when:
+
+- the repo has an npm package identity maintainers can actually control
+- at least one external adopter confirms successful installation without maintainer intervention
+- artifact verification passes on two consecutive release candidates
+- maintainer agrees to own the support posture defined in `docs/project/support-policy.md`

package/docs/project/npm-publishing.md

@@ -0,0 +1,57 @@
+---
+title: npm Publishing Setup
+status: active
+updated: 2026-04-09
+---
+
+# npm Publishing Setup
+
+This repo is prepared for npm trusted publishing from GitHub Actions, but npm-side setup is still required before the first successful publish.
+
+## Package Identity
+
+The intended published package is `@havesomecode/kibana-mcp-server`.
+
+Before enabling trusted publishing, confirm both of these are true:
+
+- the npm scope `@havesomecode` is owned by the maintainer account that will publish this package
+- the package `@havesomecode/kibana-mcp-server` is either unclaimed or already owned by that scope
+
+Do not configure trusted publishing against a package or scope you do not control.
+
+## Repo-Side Publish Workflow
+
+The authoritative workflow file is `.github/workflows/release.yml`.
+
+It is responsible for:
+
+- running `npm run verify` on `master` pushes before any publish attempt
+- running `semantic-release` on normal `master` pushes
+- publishing to npm automatically when merged history contains a releasable semantic change
+- creating Git tags and GitHub Releases from the same release event
+- using GitHub OIDC instead of npm automation tokens
+
+## npm-Side Setup
+
+After package ownership is resolved:
+
+1. Open the package settings on npmjs.com.
+2. Add a trusted publisher.
+3. Choose GitHub Actions.
+4. Set:
+   - Organization or user: `Zacaria`
+   - Repository: `kibana-mcp-server`
+   - Workflow filename: `release.yml`
+   - Environment name: leave blank unless GitHub environments are added later
+5. Save the trusted publisher.
+6. Merge a PR into `master` with a semantic title such as `feat: ...` or `fix: ...`.
+7. After the first successful publish, disable token-based publishing in npm package settings.
+
+## Publish Expectations
+
+- The workflow requires GitHub-hosted runners.
+- The workflow requires `id-token: write`.
+- The package must remain public for provenance to be generated automatically.
+- The package `repository` field must match this public GitHub repository exactly.
+- The npm package name in `package.json` must stay aligned with the package configured in npm trusted publishers.
+- Squash merge should be enabled so the semantic PR title becomes the final commit title on `master`.

package/docs/project/release-checklist.md

@@ -0,0 +1,51 @@
+---
+title: Release Checklist
+status: active
+updated: 2026-04-09
+---
+
+# Release Checklist
+
+## Preconditions
+
+- CI is green on `master`.
+- `npm run verify` passes locally.
+- The compatibility matrix is up to date (`docs/project/compatibility-matrix.md`).
+- Any new env or config requirements are documented in `README.md` and `INSTALL.md`.
+- The npm scope and package name (`@havesomecode/kibana-mcp-server`) are owned by the maintainers.
+
+## Release Authorization
+
+- Releases are created via the `Release` GitHub Actions workflow.
+- Trusted publishing for npm must point at workflow file `release.yml`.
+- Tags and GitHub Releases are created by `semantic-release` after a verified push to `master`.
+- PRs that should affect semver must use a Conventional Commit title because squash merge will carry that title onto `master`.
+- Only maintainers listed in `CODEOWNERS` should have permission to trigger releases.
+
+## Security Posture for CI/Release
+
+- Workflow permissions must be minimal (`contents: read` for CI, `contents: write` + `id-token: write` for publish).
+- Publishing to npm must use OIDC trusted publishing.
+- Do not store long-lived npm tokens in repo secrets.
+- After trusted publishing is verified, disallow token-based publishing in npm package settings.
+
+## Threat Model (Top 3)
+
+1. **Compromised GitHub Actions workflow**: mitigate with minimal permissions, required reviews, and avoiding untrusted actions.
+2. **Malicious dependency update**: mitigate with dependency review workflow and human review of automated PRs.
+3. **Accidental secrets leakage in artifacts**: mitigate with `verify-packlist` and explicit exclusion of local config files.
+
+## Steps
+
+1. Open a PR with a semantic title such as `feat: ...`, `fix: ...`, or `feat!: ...`.
+2. Run `npm run verify`.
+3. Confirm the npm package identity is publishable by this maintainer account.
+4. Configure npm trusted publishing for `release.yml`.
+5. Merge with squash merge into `master`.
+6. Confirm the `Release` workflow either exits with no release or publishes a new version.
+7. Validate the Git tag, GitHub Release notes, published package contents, and provenance.
+
+## Post-Release
+
+- Confirm install instructions still match the shipped artifact.
+- Update any compatibility claims that changed in the release.