@ketecode/loom 0.0.0-stage → 0.2.0

package/skills/node-backend-patterns/references/templates.md

@@ -0,0 +1,122 @@
+# Templates
+
+Adapt to the project's module system and libraries; these use ESM and zod.
+
+## Express: validation middleware and error handler
+
+```ts
+import type { Request, Response, NextFunction } from 'express';
+import { ZodError, type ZodType } from 'zod';
+
+export class AppError extends Error {
+  constructor(public status: number, public code: string, message: string) { super(message); }
+}
+
+export const validateBody = (schema: ZodType) => (req: Request, res: Response, next: NextFunction) => {
+  const result = schema.safeParse(req.body);
+  if (!result.success) {
+    return res.status(400).json({ error: { code: 'invalid_request', issues: result.error.issues.map((i) => ({ path: i.path.join('.'), message: i.message })) } });
+  }
+  req.body = result.data;
+  next();
+};
+
+// Register after all routes.
+export function errorHandler(err: unknown, req: Request, res: Response, next: NextFunction) {
+  if (res.headersSent) return next(err); // let Express close a half-sent response
+  if (err instanceof AppError) {
+    return res.status(err.status).json({ error: { code: err.code, message: err.message } });
+  }
+  if (err instanceof ZodError) {
+    return res.status(400).json({ error: { code: 'invalid_request' } });
+  }
+  req.log?.error({ err }, 'unhandled error');
+  res.status(500).json({ error: { code: 'internal', message: 'Something went wrong' } });
+}
+```
+
+## Express: server.ts with graceful shutdown
+
+```ts
+import { createApp } from './app.js';
+import { config } from './config.js';
+import { logger } from './logger.js';
+import { db } from './db.js';
+
+const app = createApp();
+const server = app.listen(config.port, () => logger.info({ port: config.port }, 'listening'));
+server.headersTimeout = 65_000;
+server.requestTimeout = 30_000;
+
+let shuttingDown = false;
+export const isReady = () => !shuttingDown; // the readiness route reads this
+
+async function shutdown(signal: string) {
+  if (shuttingDown) return;
+  shuttingDown = true;
+  logger.info({ signal }, 'shutting down');
+  const force = setTimeout(() => { logger.error('forced exit'); process.exit(1); }, 25_000);
+  force.unref();
+  server.close(async (err) => {
+    await db.end().catch((e) => logger.error({ err: e }, 'db close failed'));
+    process.exit(err ? 1 : 0);
+  });
+  server.closeIdleConnections();
+}
+
+process.on('SIGTERM', () => shutdown('SIGTERM'));
+process.on('SIGINT', () => shutdown('SIGINT'));
+```
+
+## Fastify: schema-validated route and shutdown
+
+```ts
+import Fastify from 'fastify';
+
+const app = Fastify({ logger: { redact: ['req.headers.authorization'] }, bodyLimit: 100_000 });
+
+app.post('/orders', {
+  schema: {
+    body: {
+      type: 'object',
+      required: ['items'],
+      additionalProperties: false, // stripped, not rejected, under Fastify's default ajv options
+      properties: { items: { type: 'array', minItems: 1, items: { type: 'string' } } },
+    },
+    response: { 201: { type: 'object', properties: { id: { type: 'string' } } } },
+  },
+}, async (req, reply) => {
+  const order = await placeOrder(req.body);
+  return reply.code(201).send(order);
+});
+
+app.addHook('onClose', async () => { await db.end(); });
+
+await app.listen({ port: Number(process.env.PORT ?? 3000), host: '0.0.0.0' });
+
+for (const signal of ['SIGTERM', 'SIGINT'] as const) {
+  process.once(signal, async () => {
+    setTimeout(() => process.exit(1), 25_000).unref();
+    await app.close();
+    process.exit(0);
+  });
+}
+```
+
+## Streaming a file download
+
+```ts
+import { createReadStream } from 'node:fs';
+import { pipeline } from 'node:stream/promises';
+
+app.get('/exports/:id', async (req, res, next) => {
+  try {
+    const path = await exportPathFor(req.params.id); // validates ownership, throws AppError(404)
+    res.setHeader('Content-Type', 'text/csv');
+    res.setHeader('Content-Disposition', `attachment; filename="export-${req.params.id}.csv"`);
+    await pipeline(createReadStream(path), res);
+  } catch (err) {
+    if (!res.headersSent) next(err); else res.destroy(err as Error);
+  }
+});
+```

package/skills/nuxt-patterns/SKILL.md

@@ -0,0 +1,103 @@
+---
+name: nuxt-patterns
+description: Nuxt 3 and 4 full-stack app guidance for choosing SSR, SPA, prerender or hybrid route rules, fetching data once with useFetch and useAsyncData instead of double-fetching with $fetch, writing Nitro server routes, wiring runtimeConfig secrets, setting SEO metadata, and tracking down hydration mismatches. Use when working in a Nuxt project on pages, server/api endpoints, nuxt.config, data loading, meta tags, or a server-versus-client rendering bug.
+license: MIT
+compatibility: Any Agent Skills host. Targets Nuxt 3.x and 4.x; Nuxt 4 differences are called out. Needs the project's package manager to run the dev server or build.
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: coding
+  kete-loom/risk: runs-commands
+  kete-loom/owner: "Kete-org"
+---
+
+# Nuxt patterns
+
+Build Nuxt pages that render the same on server and client, fetch each piece of data once, and keep secrets on the server. For plain Vue component reactivity, props and Pinia, also follow `vue-patterns`.
+
+## 0. Orient first
+
+1. Read `package.json` for the Nuxt major version and modules (`@pinia/nuxt`, `@nuxtjs/i18n`, `@nuxt/content`, `@nuxt/image`).
+2. Check the layout. Nuxt 4 uses `app/` as `srcDir` (so `~/components` is `app/components`), keeps `server/`, `public/` and `shared/` at the root. A Nuxt 4 project may keep the old layout with `srcDir: '.'`. Follow what is there.
+3. Read `nuxt.config.ts` for `ssr`, `routeRules`, `runtimeConfig`, `nitro.preset` and `app.head`.
+
+## 1. Pick a rendering mode per route
+
+| Need | Setting |
+|---|---|
+| Personalised or SEO-critical dynamic page | default SSR |
+| Marketing page, docs, blog post | `routeRules: { '/blog/**': { prerender: true } }` |
+| Mostly static but changes hourly | `{ swr: 3600 }` or `{ isr: 3600 }` on hosts that support ISR |
+| Dashboard behind login, no SEO | `{ ssr: false }` for that route |
+| Whole app is a client-only SPA | `ssr: false` at the top level |
+
+Prefer per-route `routeRules` over flipping the global `ssr` flag. Confirm the deploy target supports the rule (`isr` is host-specific).
+
+## 2. Fetch data once
+
+1. In page or component setup, use `useFetch('/api/x')` for a URL, or `useAsyncData('key', () => fn())` for any async function. Both run on the server, serialise the result into the payload, and reuse it on hydration.
+2. Never call bare `$fetch` at the top of setup in an SSR page: it runs on the server and again on the client. Use `$fetch` only in event handlers, actions, server routes, or inside `useAsyncData`.
+3. Give `useAsyncData` a stable, unique key. Calls sharing a key share state; in Nuxt 4 they must not pass conflicting `transform`, `pick`, `default` or `getCachedData` options.
+4. Make reactive inputs explicit: `useFetch('/api/items', { query: { page } })` with `page` a ref refetches automatically; for `useAsyncData` pass `watch: [page]`.
+5. Handle all states in the template with `status` (`'idle' | 'pending' | 'success' | 'error'`) and `error`, not only `data`.
+6. Nuxt 4 changes: `data` and `error` default to `undefined` (Nuxt 3: `null`), and `data` is a `shallowRef`, so mutating a nested field does not re-render. Replace the object, or pass `deep: true`.
+7. Use `lazy: true` (or `useLazyFetch`) when the page should render before the data arrives, and show a pending state.
+8. Use `server: false` only for data that must never be fetched on the server (browser-only APIs, per-user data on a cached page).
+9. During SSR, `useFetch` with a relative URL to your own API forwards the incoming request's cookies and headers (except hop-by-hop ones such as `host`). A bare `$fetch` in a composable does not; use `useRequestFetch()` when you need the incoming request's headers.
+10. For one-time app init (load the current user), use `callOnce` or a plugin, not a `useFetch` in `app.vue` that runs on every navigation.
+
+## 3. Server routes (Nitro)
+
+- Files in `server/api/` map to `/api/...`; method suffixes (`users.post.ts`) restrict the verb. `server/routes/` maps without the `/api` prefix. `server/middleware/` runs on every request, so keep it cheap.
+- Use `defineEventHandler`, read input with `getQuery`, `readBody`, `getRouterParam`, and validate it (for example `readValidatedBody(event, schema.parse)`) before use.
+- Throw `createError({ statusCode: 404, statusMessage: 'Not found' })` instead of returning error objects with a 200.
+- Check authentication and authorization in every handler that touches private data. A route in `server/api` is public unless you guard it.
+- Put code shared by server and client in `shared/` (Nuxt 4) and never import server-only modules from `app/`.
+
+## 4. Runtime config and secrets
+
+```ts
+export default defineNuxtConfig({
+  runtimeConfig: {
+    apiSecret: '',                 // server only, override with NUXT_API_SECRET
+    public: { apiBase: '/api' },   // shipped to the browser, override with NUXT_PUBLIC_API_BASE
+  },
+})
+```
+
+- Read with `useRuntimeConfig()` (in server handlers, `useRuntimeConfig(event)`).
+- Anything under `public` is visible to every visitor. Secrets go at the top level only.
+- Set values in production through `NUXT_`-prefixed environment variables; `process.env` reads in `nuxt.config` are baked in at build time.
+
+## 5. SEO and head
+
+- Use `useSeoMeta({ title, description, ogTitle, ogImage })` per page, and `useHead` for links, scripts and `htmlAttrs: { lang }`.
+- Set defaults in `app.head` in `nuxt.config.ts`; let pages override.
+- Generate canonical URLs and `og:url` from a configured site URL, not from `window.location`.
+- SEO tags only reach crawlers on SSR or prerendered routes; do not rely on them for `ssr: false` routes.
+
+## 6. Hydration mismatches
+
+When the console shows "Hydration mismatch" or "Hydration completed but contains mismatches":
+
+1. Reproduce with a production build (`nuxt build` then `nuxt preview`) and read the warning for the node that differs.
+2. Look for values that differ between server and client: `Date.now()`, `new Date().toLocaleString()`, `Math.random()`, time zones, `window`/`localStorage` reads during render, and user-agent checks.
+3. Fix by computing the value once on the server and passing it through `useState` or fetched data, by moving browser-only reads into `onMounted`, or by wrapping the subtree in `<ClientOnly>` with a fallback.
+4. Guard browser-only code with `import.meta.client` (or `.server`), not `process.client`.
+5. Check for invalid HTML nesting (a `<div>` inside a `<p>`, nested `<a>`, a `<tr>` without `<tbody>`); browsers rewrite it and the DOM no longer matches.
+6. For cross-request state, use `useState('key', () => init)` instead of a module-level `ref`, which leaks between users on the server.
+
+## Stop and ask the user
+
+- Changing the rendering mode or `nitro.preset` of a route already in production.
+- A secret is currently under `runtimeConfig.public` or committed in `nuxt.config`: flag it and ask before rotating anything.
+- The fix needs a Nuxt major upgrade.
+
+## Never
+
+- Never put API keys in `runtimeConfig.public` or client code.
+- Never hide a hydration warning with `<ClientOnly>` around a whole page without finding the cause.
+- Never leave a `server/api` handler without input validation or an auth check when it touches user data.
+
+## Report back
+
+State the files changed, the rendering mode of each touched route, how data is fetched there, the command you ran (`nuxt build`, tests, typecheck) and its result, and anything not checked in a production build.

package/skills/nuxt-patterns/evals/triggers.json

@@ -0,0 +1,16 @@
+{
+  "should_trigger": [
+    "My Nuxt page calls the API twice, once on the server and again in the browser",
+    "Prerender the blog section of our Nuxt app but keep the dashboard client-only",
+    "How do I keep the Stripe secret out of the browser using Nuxt runtimeConfig?",
+    "Add a server/api endpoint in Nuxt that validates the POST body",
+    "Fix the hydration mismatch on my Nuxt product page caused by the date"
+  ],
+  "should_not_trigger": [
+    "Why does my Vue 3 composable lose reactivity when I destructure it?",
+    "Review my Nuxt pull request for missing watcher cleanup",
+    "Write a SvelteKit form action that validates the signup form",
+    "Set up getServerSideProps in my Next.js page",
+    "Write a Pinia store for user preferences in a plain Vite Vue app"
+  ]
+}

package/skills/observability/SKILL.md

@@ -0,0 +1,125 @@
+---
+name: observability
+description: OpenTelemetry-first service instrumentation that adds structured JSON logs carrying trace IDs, RED metrics with bounded-cardinality labels and distributed traces (SDK and exporter setup, semantic conventions, W3C traceparent propagation, head and tail sampling), then turns them into SLIs, SLOs, multi-window burn-rate alerts and on-call dashboards in Grafana, Prometheus or a vendor backend. Use when instrumenting a service with OpenTelemetry, traces break across service hops, logs cannot be joined to a request, defining an SLO or error budget, replacing noisy threshold alerts with burn-rate alerts, or building the operational board on-call opens first.
+license: MIT
+compatibility: Any Agent Skills host. Works with any OpenTelemetry SDK (Java, Python, Go, Node, .NET and others) and any OTLP backend; examples use Prometheus query syntax and Grafana.
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: devops
+  kete-loom/risk: writes-files
+  kete-loom/owner: "Kete-org"
+---
+
+# Observability
+
+Make every request answerable: which one failed, where it spent its time, and whether users are hurting enough to wake someone. Logs, metrics and traces share one resource identity and one trace ID, and alerts fire on user-facing SLO burn, not on CPU.
+
+This skill is for operational telemetry. Business KPI boards belong to `metrics-dashboards`; what the on-call person does once paged belongs to `runbook-writing`.
+
+## 0. Before you start
+
+1. Find what is already there: search for `opentelemetry`, `prometheus`, `statsd`, `datadog`, `newrelic`, `logging.basicConfig`, `winston`, `zap`, `slog`, `logback`. Keep one telemetry stack; do not add a second SDK beside an existing one.
+2. Find the backend: an OpenTelemetry Collector, Grafana stack (Tempo, Loki, Mimir or Prometheus), or a vendor. If none exists and the user has not picked one, **stop and ask**; the backend decides exporters and query syntax.
+3. List the service's entry points (HTTP routes, queue consumers, cron jobs) and its outbound calls (databases, HTTP clients, queues). These are where spans and metrics go.
+
+## 1. Resource identity
+
+Set these once, through environment variables so every signal shares them:
+
+- `OTEL_SERVICE_NAME` (required; the same name in logs, metrics and traces)
+- `OTEL_RESOURCE_ATTRIBUTES=service.version=<git sha or release>,deployment.environment.name=<env>`
+- `OTEL_EXPORTER_OTLP_ENDPOINT` pointing at the Collector, not straight at a vendor, so sampling and routing can change without a redeploy.
+
+Per-language SDK bootstrap and Collector config are in `references/otel-setup.md`.
+
+## 2. Traces
+
+1. Prefer the language's auto-instrumentation (HTTP server and client, database drivers, messaging) before writing manual spans.
+2. Add manual spans only around meaningful units of work the auto layer cannot see (a pricing calculation, a batch step). Name spans by operation, low cardinality: `GET /orders/{id}`, never `GET /orders/8812`.
+3. Use the semantic conventions for attributes (`http.request.method`, `http.route`, `http.response.status_code`, `db.system.name`, `server.address`); custom attributes get your own namespace (`app.order.tier`).
+4. Record errors: set span status to error and record the exception on the span that failed.
+5. Propagation: W3C `traceparent`/`tracestate` is the default. Check every hop: async queues need the context injected into message headers and extracted in the consumer; thread pools and background tasks need the context carried explicitly.
+6. Sampling:
+   - Start with `OTEL_TRACES_SAMPLER=parentbased_traceidratio` and `OTEL_TRACES_SAMPLER_ARG` (for example `0.1`) so children follow the root's decision.
+   - To keep all errors and slow requests, do tail sampling in the Collector (`tail_sampling` processor), and make sure all spans of a trace reach the same Collector instance.
+   - Never sample metrics. Rates come from metrics, not from sampled traces.
+
+## 3. Metrics
+
+1. Per entry point, emit RED: request rate, errors, duration as a histogram (`http.server.request.duration` in seconds from auto-instrumentation, or your own). Per dependency, the same on the client side. Per queue: depth and age of oldest message.
+2. Labels must be bounded. Never put user IDs, emails, raw URLs, order IDs or error messages in a label. Use the route template and the status code class.
+3. A latency SLI counts requests under the threshold, so the histogram needs a bucket boundary exactly at it. The default OpenTelemetry HTTP buckets are 0.005, 0.01, 0.025, 0.05, 0.075, 0.1, 0.25, 0.5, 0.75, 1, 2.5, 5, 7.5, 10 s: pick an SLO threshold on one of them, or add the boundary with a metrics view (or use exponential histograms if the backend supports them).
+4. Add saturation for whatever runs out first: connection pool in use, worker queue, memory against limit.
+
+## 4. Logs
+
+1. Structured JSON, one event per line, to stdout. Fields: `timestamp`, `severity`, `message`, `service.name`, `trace_id`, `span_id`, plus event fields.
+2. Inject `trace_id`/`span_id` with the SDK's log bridge or logging instrumentation, so a log line links to its trace.
+3. Log events, not narration: one line per failed operation with its cause and inputs that are safe to log. Never log secrets, tokens, passwords, full card numbers or request bodies containing personal data; redact at the logger, not at query time.
+4. Default level INFO in production; DEBUG behind a runtime switch.
+
+## 5. SLIs and SLOs
+
+1. Pick 1 to 3 SLIs per user journey, each a ratio of good events to valid events:
+   - Availability: non-5xx responses / all responses (decide whether 429 and 4xx count; write it down).
+   - Latency: requests faster than the threshold / all requests, measured at the edge closest to the user you can instrument.
+2. Set the SLO target with the owner (for example 99.9% over 28 or 30 days). **Stop and ask** if no one owns the number; never invent a target.
+3. Error budget = 1 − target. Write the SLO as a file in the repo (definition, query, window, owner, what happens when the budget is spent).
+
+## 6. Burn-rate alerts
+
+Page on how fast the budget burns, using a long and a short window together so alerts fire fast and reset fast. The standard pairs for a 30-day SLO (from the Google SRE Workbook):
+
+| Severity | Long window | Short window | Burn rate | Budget spent at trigger |
+|---|---|---|---|---|
+| Page | 1h | 5m | 14.4 | 2% |
+| Page | 6h | 30m | 6 | 5% |
+| Ticket | 3d | 6h | 1 | 10% |
+
+Query templates (Prometheus recording rules and alert rules) are in `references/slo-alerts.md`.
+
+Alert rules:
+
+- Every paging alert links to a runbook and a dashboard.
+- Remove or demote cause-based alerts (CPU, memory, single pod restart) to tickets unless they predict an SLO breach no other alert catches.
+- Low-traffic services: burn-rate alerts flap on few requests; add a minimum request count or use synthetic probes.
+
+## 7. On-call dashboard
+
+One board per service, top to bottom:
+
+1. SLO status and remaining error budget, with the burn rate.
+2. RED for the entry points: rate, error ratio, p50/p95/p99 latency.
+3. Dependencies: the same RED, client side, per dependency.
+4. Saturation: pools, queues, memory and CPU against limits.
+5. Deploy and feature-flag annotations on every time series.
+6. Links: logs filtered to the service, trace search, runbook.
+
+Use template variables for environment and instance; keep it under about 20 panels. Panel and query guidance is in `references/slo-alerts.md`.
+
+## 8. Verify
+
+1. Run the service locally or in a test environment with the Collector's `debug` exporter (or the backend) and send a request.
+2. Confirm: one trace spans every hop, including through a queue; the log line for that request carries the same `trace_id`; the RED metrics appear with only bounded labels.
+3. Evaluate each alert expression against recent data and check it would not have fired continuously.
+
+## Never
+
+- Never put unbounded values in metric labels or span names.
+- Never log secrets or personal data, or ship telemetry to a third party the user has not approved.
+- Never page on a symptom with no user impact and no runbook.
+- Never set an SLO target without an owner agreeing to it.
+
+## Report back
+
+```
+## Observability: <service>
+Instrumented: <entry points, dependencies, signals>
+Resource: service.name=<>, version source, environment
+Sampling: <head ratio, tail policy>
+SLOs: <SLI, target, window> per journey
+Alerts: <name, windows, burn rate, runbook link>
+Dashboard: <file or URL>
+Verified: <trace across hops yes/no, logs joined yes/no, alert dry run>
+Open questions: <owner, targets, backend>
+```

package/skills/observability/evals/triggers.json

@@ -0,0 +1,17 @@
+{
+  "should_trigger": [
+    "Add OpenTelemetry tracing to our Python and Go services and send it to a Collector",
+    "Our traces stop at the Kafka consumer, the span context isn't carried across the queue. Fix the propagation.",
+    "Define an availability SLO for the checkout API and write multi-window burn-rate alerts in Prometheus",
+    "Build the Grafana board on-call should open first when the payments service pages",
+    "Our log lines can't be matched to a request; add trace_id and span_id to the JSON logs",
+    "We get paged for CPU spikes nobody cares about, replace them with error budget alerts"
+  ],
+  "should_not_trigger": [
+    "Design a KPI dashboard for the sales team showing monthly recurring revenue and churn",
+    "Write a runbook for the HighErrorRate alert with diagnosis steps and escalation contacts",
+    "Write a blameless postmortem for yesterday's database outage",
+    "Plan a canary rollout with automatic rollback for the new pricing service",
+    "Set up a Helm chart and liveness probes for our API on Kubernetes"
+  ]
+}

package/skills/observability/references/otel-setup.md

@@ -0,0 +1,87 @@
+# OpenTelemetry setup
+
+Read this when bootstrapping an SDK or a Collector. Package names and flags move between releases: check the language's page under opentelemetry.io/docs/languages/ for the current version before pinning.
+
+## Standard environment variables
+
+| Variable | Example | Notes |
+|---|---|---|
+| `OTEL_SERVICE_NAME` | `checkout-api` | Same name in every signal |
+| `OTEL_RESOURCE_ATTRIBUTES` | `service.version=4f2c1a9,deployment.environment.name=prod` | Comma-separated key=value |
+| `OTEL_EXPORTER_OTLP_ENDPOINT` | `http://otel-collector:4318` | 4317 gRPC, 4318 HTTP |
+| `OTEL_EXPORTER_OTLP_PROTOCOL` | `http/protobuf` | or `grpc` |
+| `OTEL_TRACES_SAMPLER` | `parentbased_traceidratio` | |
+| `OTEL_TRACES_SAMPLER_ARG` | `0.1` | Ratio for the root sampler |
+| `OTEL_PROPAGATORS` | `tracecontext,baggage` | The default |
+
+## Auto-instrumentation by language
+
+- **Java**: attach the agent, `java -javaagent:opentelemetry-javaagent.jar -jar app.jar`.
+- **Python**: `pip install opentelemetry-distro opentelemetry-exporter-otlp`, then `opentelemetry-bootstrap -a install`, run with `opentelemetry-instrument python app.py`.
+- **Node.js**: `npm install @opentelemetry/sdk-node @opentelemetry/auto-instrumentations-node`, start with `node --require @opentelemetry/auto-instrumentations-node/register app.js` (the SDK must load before the app's own imports).
+- **.NET**: the `OpenTelemetry.Extensions.Hosting` package plus `OpenTelemetry.Instrumentation.AspNetCore` and `.Http`, registered with `services.AddOpenTelemetry().WithTracing(...).WithMetrics(...)`; or the zero-code automatic instrumentation.
+- **Go**: no agent; wire `otelhttp` handlers and transports and the `otel/sdk` trace and metric providers in `main`, and call `Shutdown` on exit so the last spans flush.
+
+Flush on shutdown in every language; short-lived jobs lose their spans otherwise.
+
+## Manual span (pattern)
+
+```python
+from opentelemetry import trace
+tracer = trace.get_tracer("app.pricing")
+
+with tracer.start_as_current_span("price_quote") as span:
+    span.set_attribute("app.quote.items", len(items))
+    try:
+        quote = compute(items)
+    except Exception as exc:
+        span.record_exception(exc)
+        span.set_status(trace.Status(trace.StatusCode.ERROR))
+        raise
+```
+
+## Propagating through a queue
+
+Producer: `propagate.inject(headers)` into the message headers. Consumer: `ctx = propagate.extract(headers)` and start the consumer span with that context (as a child, or as a new trace with a span link for batch consumers).
+
+## Minimal Collector config
+
+```yaml
+receivers:
+  otlp:
+    protocols:
+      grpc:
+        endpoint: 0.0.0.0:4317
+      http:
+        endpoint: 0.0.0.0:4318
+processors:
+  memory_limiter:
+    check_interval: 1s
+    limit_percentage: 80
+  batch: {}
+  tail_sampling:
+    decision_wait: 10s
+    policies:
+      - name: errors
+        type: status_code
+        status_code: { status_codes: [ERROR] }
+      - name: slow
+        type: latency
+        latency: { threshold_ms: 1000 }
+      - name: baseline
+        type: probabilistic
+        probabilistic: { sampling_percentage: 10 }
+exporters:
+  debug: {}
+  otlp:
+    endpoint: tempo:4317
+    tls: { insecure: true }   # only inside a private network
+service:
+  pipelines:
+    traces:
+      receivers: [otlp]
+      processors: [memory_limiter, tail_sampling, batch]
+      exporters: [otlp]
+```
+
+`tail_sampling` ships in the Collector contrib distribution, not core. With several Collector replicas, route by trace ID (the `loadbalancing` exporter) in a first tier so one instance sees the whole trace.

package/skills/observability/references/slo-alerts.md

@@ -0,0 +1,70 @@
+# SLO queries, burn-rate alerts and dashboard panels
+
+Read this when writing recording rules, alert rules or dashboard queries. Metric names below assume OpenTelemetry HTTP server metrics exported to Prometheus (`http_server_request_duration_seconds_*`); rename to what the service actually exposes. When OTLP metrics reach Prometheus, `service.name` becomes the `job` label (`<service.namespace>/<service.name>` if a namespace is set) and `service.instance.id` becomes `instance`; resource attributes are not copied to labels unless the exporter is configured to (for example `resource_to_telemetry_conversion` or `target_info` joins). Check the real label names in the backend before writing rules.
+
+## Recording rules (availability SLI)
+
+```yaml
+groups:
+  - name: slo-checkout
+    rules:
+      - record: slo:errors:ratio_rate5m
+        expr: |
+          sum(rate(http_server_request_duration_seconds_count{job="checkout-api",http_response_status_code=~"5.."}[5m]))
+          /
+          sum(rate(http_server_request_duration_seconds_count{job="checkout-api"}[5m]))
+      # repeat with [30m], [1h], [6h], [3d] and [30d] as slo:errors:ratio_rate30m, ... (the 30d one feeds the budget panel)
+```
+
+Latency SLI (good = faster than 0.25 s; the `le` value must be an existing bucket boundary, an approximate one silently measures a different threshold):
+
+```
+1 - (
+  sum(rate(http_server_request_duration_seconds_bucket{job="checkout-api",le="0.25"}[5m]))
+  /
+  sum(rate(http_server_request_duration_seconds_count{job="checkout-api"}[5m]))
+)
+```
+
+## Multi-window burn-rate alerts (SLO 99.9%, budget 0.001)
+
+```yaml
+      - alert: CheckoutErrorBudgetBurnFast
+        expr: |
+          slo:errors:ratio_rate1h > (14.4 * 0.001)
+          and
+          slo:errors:ratio_rate5m > (14.4 * 0.001)
+        labels: { severity: page }
+        annotations:
+          summary: "checkout-api burning error budget 14x"
+          runbook_url: "https://<runbooks>/checkout-api/error-budget"
+          dashboard: "https://<grafana>/d/checkout-api"
+      - alert: CheckoutErrorBudgetBurnMedium
+        expr: |
+          slo:errors:ratio_rate6h > (6 * 0.001)
+          and
+          slo:errors:ratio_rate30m > (6 * 0.001)
+        labels: { severity: page }
+      - alert: CheckoutErrorBudgetBurnSlow
+        expr: |
+          slo:errors:ratio_rate3d > (1 * 0.001)
+          and
+          slo:errors:ratio_rate6h > (1 * 0.001)
+        labels: { severity: ticket }
+```
+
+Burn rate = observed error ratio / error budget. A burn rate of 1 spends exactly the budget over the SLO window. Tools such as Sloth or Pyrra generate these rules from a short SLO spec; use one if the team already does.
+
+## Dashboard panels (Grafana)
+
+| Panel | Query sketch | Visual |
+|---|---|---|
+| Error budget remaining | `1 - (slo:errors:ratio_rate30d / 0.001)` | Stat, red under 25% |
+| Burn rate 1h | `slo:errors:ratio_rate1h / 0.001` | Stat with thresholds 1, 6, 14.4 |
+| Request rate | `sum by (http_route) (rate(..._count[5m]))` | Time series |
+| Error ratio | `sum by (http_route) (rate(..._count{http_response_status_code=~"5.."}[5m])) / sum by (http_route) (rate(..._count[5m]))` | Time series |
+| Latency p95/p99 | `histogram_quantile(0.99, sum by (le) (rate(..._bucket[5m])))` | Time series |
+| Dependency latency | same on `http_client_request_duration_seconds` by `server_address` | Time series |
+| Saturation | pool in use / pool max, queue depth | Time series with limit line |
+
+Add annotations from the deploy pipeline (Grafana annotations API or a `deployments` metric), and data links from latency panels to the trace backend filtered by service and time range. Keep dashboards as JSON in the repo, provisioned from files, so changes are reviewed.

package/skills/open-source-release/SKILL.md

@@ -0,0 +1,107 @@
+---
+name: open-source-release
+description: Takes a private or internal codebase public safely by scanning the working tree and full git history for secrets, personal data and internal hostnames with gitleaks and trufflehog, rewriting history with git filter-repo or starting a fresh history, choosing an outbound licence and checking third-party licence compatibility, adding README, CONTRIBUTING, SECURITY and CODE_OF_CONDUCT files and public CI, then walking a pre-publish checklist with explicit sign-off points. Use when someone wants to open-source an internal project, flip a private GitHub repository to public, or publish company code under an open licence for the first time.
+license: MIT
+compatibility: Any Agent Skills host. Needs git; secret scanning uses gitleaks or trufflehog, history rewriting uses git-filter-repo. Licence scanners depend on the ecosystem.
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: devops
+  kete-loom/risk: runs-commands
+  kete-loom/requires: "git, gitleaks, git-filter-repo"
+  kete-loom/owner: "Kete-org"
+---
+
+# Open-source release
+
+Make a private repository safe to publish. Once a repository is public, anything in its history is copied by forks, mirrors and scrapers within minutes, so every check happens **before** the visibility flip, and none of it can be undone afterwards.
+
+This skill is engineering preparation, not legal advice. The owner of the code (usually the employer) must approve the release and the licence; a lawyer or the company's open-source programme office should review licence and trademark questions.
+
+## 0. Stop and ask first
+
+Before doing any work, confirm with the user:
+
+1. Who owns the code and has approved publishing it (name the person or the approval record).
+2. Whether contributors outside the company ever committed (their rights matter for relicensing).
+3. Whether to **keep history** (rewrite and scrub it) or **publish a fresh history** (one squashed initial commit). A fresh history is the safest default for internal code; keep history only if the user wants it and the scan in step 1 is clean or fully remediated.
+
+Work in a **fresh clone** (`git clone --mirror` for scanning and rewriting history, a normal clone for the fresh-history route) so you never rewrite the team's working copy.
+
+**Publish to a new public repository by default** rather than flipping the existing private one to public. Flipping visibility also exposes everything attached to the repository: issues, pull requests and their review comments, wiki, releases, Actions logs and artifacts, and `refs/pull/*` commits that a history rewrite cannot remove. Flip the existing repository only if the user explicitly wants that and has reviewed all of it.
+
+## 1. Scan for secrets, personal data and internal details
+
+Scan the full history of every ref, not just the tip:
+
+- `gitleaks git -v --log-opts="--all" --report-path gitleaks-history.json .`
+- `gitleaks dir -v --report-path gitleaks-tree.json .` (working tree, including untracked files you plan to publish)
+- `trufflehog git file://<path-to-clone> --results=verified,unknown` (run from outside the repo; it tries keys against providers, so tell the user it makes network calls)
+
+Then search the codebase and history (`git log -p --all -S <term>` / `git grep`) for what scanners miss, including commit metadata (`git log --all --format='%an <%ae> %cn <%ce>' | sort -u` and commit messages), which can carry personal emails, ticket links and customer names:
+
+- internal hostnames and domains (`*.internal`, `*.corp`, `*.local`, VPN and intranet names), private IP ranges, cloud account and project IDs, S3 bucket names;
+- customer names, employee names and emails, phone numbers, real data in fixtures, seeds, test snapshots and screenshots;
+- committed `.env`, `*.pem`, `*.p12`, `id_rsa`, kubeconfig, `terraform.tfstate`, database dumps, `.npmrc`/`.pypirc` with tokens;
+- comments with security issues, incident details, unreleased product names, profanity about customers;
+- vendored proprietary code, internal packages pulled from a private registry, licensed fonts or images.
+
+Triage each hit as **live secret**, **dead secret**, **PII**, **internal detail** or **false positive**.
+
+## 2. Remediate
+
+1. **Rotate every real secret first**, live or "probably dead". Scrubbing history does not un-leak a key someone already copied. Record who rotated what.
+2. Remove PII and internal details from the current tree with normal commits.
+3. Then deal with history, following `references/history-scrub.md`:
+   - fresh history: copy the cleaned tree into a new repository with one initial commit;
+   - keep history: `git filter-repo --sensitive-data-removal --replace-text replacements.txt` and `--invert-paths --path <file>` for whole files; `--replace-message` for commit messages and `--mailmap` for author identities; then re-run every scan from step 1 until it is clean.
+4. Add the remaining false positives to a `.gitleaksignore` (fingerprints) so CI starts clean.
+
+## 3. Licence
+
+1. Ask the user which outbound licence the owner has chosen. If undecided, lay out the usual options without deciding for them: permissive (MIT, Apache-2.0 which adds an explicit patent grant, BSD-3-Clause), weak copyleft (MPL-2.0), strong copyleft (GPL-3.0, AGPL-3.0 for network services).
+2. Add the full licence text as `LICENSE` and an SPDX identifier in the package manifest (`"license": "Apache-2.0"`, `license = "MIT"`). Optional per-file `SPDX-License-Identifier` headers; `reuse lint` checks them if the project adopts REUSE.
+3. Inventory third-party licences with the ecosystem's tool (`references/history-scrub.md` lists them) and flag: no licence, unknown licence, copyleft dependencies incompatible with the chosen licence, and copied-in code whose origin is unclear. **Stop and ask** on any flag; a qualified person decides compatibility.
+4. If outside contributors will be accepted, ask whether the owner wants a DCO sign-off or a CLA. Don't pick one for them.
+
+## 4. Community and security files
+
+Add or update, matching the project's real process (never promise response times nobody agreed to):
+
+- `README.md`: what it is, status (experimental / stable), install, a working quick-start, how to run tests, licence.
+- `CONTRIBUTING.md`: dev setup, test and lint commands, branch and PR rules, DCO/CLA if any.
+- `SECURITY.md`: how to report a vulnerability privately (enable GitHub private vulnerability reporting, or a monitored address), supported versions. Ask the user for the contact.
+- `CODE_OF_CONDUCT.md`: usually the Contributor Covenant (3.0 is current); fill in a real enforcement contact the user gives you.
+- Issue and PR templates, `CODEOWNERS` if the team uses it.
+- Remove internal-only files: deploy scripts for company infrastructure, internal runbooks, `.github/workflows` that use self-hosted runners or internal secrets.
+
+## 5. Public CI
+
+- A workflow that builds, lints and tests on pull requests from forks, using no repository secrets on `pull_request` events.
+- A secret scan on every push and PR (gitleaks action or `gitleaks git` in a job).
+- Least-privilege `permissions:` on the token; for depth on workflow hardening use the `github-actions-ci` skill if installed.
+- Enable secret scanning and push protection, Dependabot or equivalent, and branch protection on the default branch.
+
+## 6. Pre-publish checklist
+
+Go through `references/history-scrub.md` "Final checklist" with the user. **Stop and ask for explicit sign-off** before:
+
+- force-pushing rewritten history anywhere;
+- creating the public repository or changing visibility to public;
+- publishing to a package registry.
+
+Never flip visibility yourself without that sign-off, and never publish while any scan finding is unresolved.
+
+## Report
+
+```
+## Open-source readiness: <repo>
+Approval: <who approved, or MISSING>
+History: fresh | rewritten (<tool>, first changed commit <sha>)
+Secrets: <n found> / <n rotated> / <n remaining>
+PII and internal details: <removed items, or none>
+Licence: <SPDX id> | third-party flags: <list or none>
+Files added: README, CONTRIBUTING, SECURITY, CODE_OF_CONDUCT, ...
+CI: <workflow names> | secret scan in CI: yes/no
+Blocking before publish: <list, or none>
+Needs human sign-off: <owner approval, licence review, visibility flip>
+```