@ketecode/loom 0.0.0-stage → 0.2.0

package/skills/cisco-ios-config/SKILL.md

@@ -0,0 +1,101 @@
+---
+name: cisco-ios-config
+description: Reads and writes Cisco IOS and IOS-XE running configuration by hand without cutting off access, covering access and trunk switchports, VLANs and VTP, named extended ACLs edited by sequence number, static routes and basic OSPF, SSH and local user hardening, config archive with configure replace and revert timers, and the show commands that prove each change worked. Use when someone needs CLI commands for a Catalyst switch or ISR/ASR/Catalyst 8000 router, wants a pasted show running-config explained, is about to change a trunk, ACL or VTY line remotely, or needs to roll a Cisco device back to an earlier config.
+license: MIT
+compatibility: Any Agent Skills host. Works from pasted configuration; live use needs an SSH or console session to the device. Syntax varies by platform and release; check the command reference for the exact IOS/IOS-XE version.
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: devops
+  kete-loom/risk: read-only
+  kete-loom/owner: "Kete-org"
+---
+
+# Cisco IOS and IOS-XE configuration
+
+Produce Cisco CLI changes that are minimal, reversible and verified, and explain existing configuration accurately. The operator pastes the commands; this skill writes them, the safety net and the checks.
+
+For a per-area list of verification commands and expected output, read `references/verification.md`.
+
+## 0. Before writing any command
+
+1. Get `show version` (platform, IOS or IOS-XE release) and the relevant section of the running config: `show running-config | section <keyword>` or `show running-config interface <if>`. Never write a change against a config you have not seen.
+2. Ask how the operator is connected: console, or SSH through which interface and VLAN. Any change on that path is a **lockout risk**.
+3. **Stop and ask** before changing: the management VLAN/SVI, the uplink trunk, VTY `access-class`, AAA/`login` settings, the default route, or routing toward the management network. Propose the change with the revert timer from step 1 below and wait for agreement.
+
+## 1. Safety net for every remote change
+
+Enable the archive once (if `show archive` says it is not configured):
+
+```
+archive
+ path flash:archive
+ maximum 10
+ write-memory
+```
+
+Use `bootflash:` instead of `flash:` where that is the platform's local file system. `write-memory` saves an archive copy each time the config is saved.
+
+Then, for each change:
+
+```
+configure terminal revert timer 10
+ ... changes ...
+end
+```
+
+Verify (step 4). If good, `configure confirm` within the timer, then save. If you lose access, the device rolls back to the archived config when the timer (minutes) runs out. Where the archive is not available, the older fallback is `reload in 10` before the change and `reload cancel` after verifying; it only works if the startup config is the known-good one, and it reboots the device.
+
+To return to a saved state on purpose: `configure replace flash:<file>` (replaces the whole running config, unlike `copy <file> running-config`, which only merges). Preview with `show archive config differences flash:<file> system:running-config`.
+
+## 2. Writing changes
+
+**Interfaces and VLANs**
+- Access port: `switchport mode access`, `switchport access vlan <id>`, `spanning-tree portfast` (edge ports only), `description <what is connected>`.
+- Trunks: add VLANs with `switchport trunk allowed vlan add <ids>`. `switchport trunk allowed vlan <ids>` without `add` **replaces** the whole list and is a classic outage. Remove with `remove`.
+- Native VLAN: `switchport trunk native vlan <id>` must match on both ends, or untagged traffic (and often the management path) breaks and CDP logs a native VLAN mismatch. Change it with the revert timer running, and plan both ends of the link.
+- Some platforms need `switchport trunk encapsulation dot1q` before `switchport mode trunk`.
+- Create VLANs with `vlan <id>` + `name <name>`. Check `show vtp status` first: a switch in VTP server/client mode can have its VLAN database overwritten by a higher revision. Recommend `vtp mode transparent` or `off` unless VTP is deliberately in use.
+- Reset a port to defaults with `default interface <if>` rather than removing lines one by one.
+
+**ACLs**
+- Use named extended ACLs with explicit sequence numbers: `ip access-list extended <NAME>`, `10 permit tcp 10.1.0.0 0.0.255.255 host 10.2.0.5 eq 443`. Remember the implicit `deny any` at the end; add an explicit `deny ip any any log` only when the operator wants the logging.
+- Edit in place: insert with a new sequence number, delete with `no <seq>`, renumber with `ip access-list resequence <NAME> 10 10`. Never delete and re-create an ACL that is applied to a live interface or VTY line.
+- Apply: `ip access-group <NAME> in|out` on the interface; `access-class <NAME> in` under `line vty 0 15` (check how many VTY lines exist with `show line`).
+- Wildcard masks are inverse: `/24` is `0.0.0.255`.
+
+**Routing basics**
+- Static: `ip route <prefix> <mask> <next-hop> [distance] name <label>`. A floating backup route uses a higher distance than the primary.
+- OSPF: `router ospf <pid>`, `router-id <x.x.x.x>`, `passive-interface default` then `no passive-interface <uplink>`, and `network <net> <wildcard> area <n>` or `ip ospf <pid> area <n>` on the interface. Changing a router ID or area on a live router resets adjacencies; plan a window.
+- Never remove `router ospf` or `router bgp` to "start clean" on a live device.
+
+**Management hardening**
+- `ip ssh version 2` (or the release default), `transport input ssh` under VTY lines, `login local` or AAA, `exec-timeout 10 0`.
+- Local users: `username <u> privilege 15 algorithm-type scrypt secret <pw>` and `enable algorithm-type scrypt secret <pw>` where the release supports it. Type 7 (`password` + `service password-encryption`) is reversible; do not treat it as protection.
+- `no ip http server` unless the web UI is needed; prefer `ip http secure-server` if it is.
+
+## 3. Explaining a pasted config
+
+Go section by section (interfaces, VLANs, ACLs, routing, management, AAA, logging/NTP/SNMP). For each: what it does, anything risky (any/any rules, SNMP `public`, telnet enabled, type 7 or plaintext passwords, unused ports in VLAN 1 and up), and anything inconsistent (ACL referenced but not defined, VLAN on a trunk that does not exist). Replace every password, secret, key and community with `<redacted>` in your reply.
+
+## 4. Verify every change
+
+Run the matching checks from `references/verification.md` and compare with the output captured before the change. Minimum: `show ip interface brief`, the section you changed, `show logging | include <if or feature>`, and reachability from the management station. Only then `configure confirm` and `copy running-config startup-config` (or `write memory`).
+
+## Never
+
+- `write erase`, `erase startup-config`, `delete flash:*`, `reload` without a scheduled `reload cancel` plan, or `format`.
+- `no vlan <id>` or trunk allowed-list changes on uplinks without checking which ports and neighbors use the VLAN.
+- Paste a large config block into a live session without a revert timer.
+- Save to startup before the change is verified.
+- Echo secrets back to the user, even from their own paste.
+
+## Report back
+
+```
+Device: <hostname>, platform <model>, release <version>
+Change: <one line>
+Commands: <block, with revert timer wrapping>
+Verify: <show commands and the expected result>
+Rollback: <configure revert now / configure replace <file> / reload cancel>
+Lockout risk: <none | what could cut access and how the timer covers it>
+```

package/skills/cisco-ios-config/evals/triggers.json

@@ -0,0 +1,18 @@
+{
+  "should_trigger": [
+    "I need to add VLAN 40 to the trunk on Gi1/0/48 of our Catalyst 9300 without breaking the other VLANs",
+    "Give me the IOS-XE commands to restrict SSH on the VTY lines to the 10.10.0.0/16 admin subnet",
+    "Explain what each part of this show running-config from our ISR 4331 is doing",
+    "How do I roll this Cisco switch back to yesterday's config after a bad change?",
+    "Change the native VLAN on a Cisco trunk remotely without locking myself out",
+    "Write a named extended ACL on IOS that only lets the web servers reach the database on 5432"
+  ],
+  "should_not_trigger": [
+    "Our BGP neighbor to the upstream ISP shows Idle (PfxCt), what happened?",
+    "Write an Ansible playbook using cisco.ios.ios_vlans to roll VLANs out to 80 switches",
+    "Audit this pfSense export and MikroTik config for ports open to the internet",
+    "Our Wi-Fi clients get an IP but can't load any websites, how do I narrow it down?",
+    "Design VLANs for my home lab with a guest network and an IoT network",
+    "Write a Kubernetes NetworkPolicy so only the API pods can reach Postgres"
+  ]
+}

package/skills/cisco-ios-config/references/verification.md

@@ -0,0 +1,63 @@
+# Verification commands
+
+Capture each relevant command before and after a change. Exact output columns vary by platform and release.
+
+## Device and config state
+
+| Command | Look for |
+|---|---|
+| `show version` | Platform, release, uptime, config register |
+| `show running-config \| section <kw>` | The block you changed, as the device stores it |
+| `show archive` | Archive enabled, the most recent archive file names |
+| `show archive config differences <a> <b>` | Line-level diff between two configs (for example an archive file and `system:running-config`) |
+| `show archive log config all` | Who changed what, if `archive` + `log config` + `logging enable` are configured |
+| `show logging` | `%LINK-3-UPDOWN`, `%LINEPROTO-5-UPDOWN`, `%SYS-5-CONFIG_I`, error messages after the change |
+
+## Interfaces and switching
+
+| Command | Look for |
+|---|---|
+| `show ip interface brief` | Status/Protocol `up up`; `administratively down` means `shutdown` |
+| `show interfaces status` | Per port: VLAN, duplex, speed, `err-disabled`, `notconnect` |
+| `show interfaces <if>` | Input/CRC errors, output drops, duplex mismatch symptoms |
+| `show interfaces trunk` | Mode, native VLAN, allowed VLANs and VLANs forwarding on each trunk |
+| `show vlan brief` | VLAN exists, active, and which access ports are in it |
+| `show vtp status` | VTP mode and configuration revision |
+| `show spanning-tree vlan <id>` | Root bridge, port roles; blocked ports you did not expect |
+| `show mac address-table interface <if>` | Hosts learned on the port |
+| `show cdp neighbors detail` / `show lldp neighbors` | What is cabled to each port |
+| `show errdisable recovery` | Why a port went err-disabled and whether it recovers |
+
+## ACLs
+
+| Command | Look for |
+|---|---|
+| `show access-lists <NAME>` | Sequence numbers and per-entry match counters rising for the traffic you expect |
+| `show ip interface <if> \| include access list` | Which ACL is applied inbound and outbound |
+| `show line` / `show running-config \| section line vty` | VTY line count and the `access-class` applied |
+
+## Routing
+
+| Command | Look for |
+|---|---|
+| `show ip route <prefix>` | Which source and next hop won, and its distance/metric |
+| `show ip route summary` | Route counts per source, before vs after |
+| `show ip protocols` | Running routing processes, networks, passive interfaces |
+| `show ip ospf neighbor` | Adjacencies in `FULL` (or `2WAY` to DROTHER on broadcast segments) |
+| `show ip ospf interface brief` | Interfaces in OSPF, area, cost, state |
+| `ping <ip> source <if>` / `traceroute <ip>` | Reachability along the path you changed |
+
+## Management
+
+| Command | Look for |
+|---|---|
+| `show ip ssh` | SSH enabled and version |
+| `show users` | Your own session still listed, and from which line |
+| `show ntp associations` | A synced peer (`*`) so logs have correct timestamps |
+
+## Sources
+
+- `configure terminal revert timer` and `configure revert` (1 to 120 minutes), `configure replace`: https://www.cisco.com/c/en/us/td/docs/ios-xml/ios/fundamentals/command/cf_command_ref/C_commands.html
+- Archive `maximum` (1 to 14, default 10) and configuration rollback: https://www.cisco.com/c/en/us/td/docs/switches/lan/catalyst9500/software/release/16-6/configuration_guide/sys_mgmt/b_166_sys_mgmt_9500_cg/b_166_sys_mgmt_9500_cg_chapter_01001.html
+- Configuration change logger (`archive` / `log config` / `logging enable`, `show archive log config`): https://www.cisco.com/c/en/us/td/docs/routers/ios/config/17-x/syst-mgmt/b-system-management/m_cm-config-logger-0.html
+- Type 8 and type 9 (`algorithm-type scrypt`) secrets and release support: https://sec.cloudapps.cisco.com/security/center/content/CiscoSecurityAdvisory/cisco-sa-npe-hardening-Dkel83jP

package/skills/clickhouse-patterns/SKILL.md

@@ -0,0 +1,101 @@
+---
+name: clickhouse-patterns
+description: ClickHouse table and query design for analytics, choosing a MergeTree family engine, ordering the sorting key for the filters that matter, keeping partitions coarse, building incremental and refreshable materialised views, batching or async-inserting writes to avoid too many parts, and reading EXPLAIN and system tables to make slow queries fast. Use when creating or changing ClickHouse tables, ingesting events into ClickHouse, a ClickHouse query scans too many rows, or deduplication and rollups give unexpected results.
+license: MIT
+compatibility: Any Agent Skills host. SQL runs in clickhouse-client or any ClickHouse driver. ClickHouse Cloud uses SharedMergeTree under the same MergeTree syntax; self-hosted replication uses Replicated* engines.
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: data
+  kete-loom/risk: runs-commands
+  kete-loom/requires: "clickhouse-client"
+  kete-loom/owner: "Kete-org"
+---
+
+# ClickHouse patterns
+
+ClickHouse is fast when it reads few granules of few columns, and when it receives few, large inserts. Almost every problem is a sorting key, a partition key or an insert pattern that breaks one of those. Engine details and view recipes are in `references/engines-and-views.md`.
+
+## 0. Before you start
+
+1. Get the version and deployment: `SELECT version()`, and whether it's ClickHouse Cloud, a single server, or a replicated cluster (`SELECT * FROM system.clusters`). Use the engine family the existing tables use.
+2. Read the current table: `SHOW CREATE TABLE db.events`. Never guess the sorting key.
+3. List the top queries the table must serve: which columns they filter on, group by and return, and the time range. If the table already exists, pull them from `system.query_log` (see section 5). If you can't get them, **stop and ask the user**; the sorting key depends on them.
+4. The sorting key and partition key can't be changed in place. Changing them means a new table and a backfill (`INSERT INTO new SELECT * FROM old`, in chunks). Agree that plan with the user before starting.
+5. Never run `DROP TABLE`, `TRUNCATE`, `ALTER TABLE ... DROP PARTITION`, `ALTER TABLE ... DELETE/UPDATE` or `OPTIMIZE ... FINAL` on a shared or production server without explicit approval. Mutations rewrite whole parts and can run for hours.
+
+## 1. Sorting key (ORDER BY)
+
+The sorting key decides how much data a query can skip. The primary index is sparse: one entry per granule (8192 rows by default).
+
+1. Start with the columns most queries filter on with equality, usually a tenant, project or event type.
+2. Order them from **low to high cardinality**: `ORDER BY (tenant_id, event_type, toDate(ts), user_id)`. Low-cardinality leading columns also compress better.
+3. Put the time column after the equality filters, at the coarsest grain the queries need (`toDate(ts)` or `toStartOfHour(ts)` rather than the raw timestamp), unless queries are mainly time-range scans across all tenants.
+4. Keep it to about four or five columns. Columns no query filters on don't belong in it.
+5. `PRIMARY KEY` defaults to `ORDER BY`. Make it a shorter prefix only if the index is too big to keep in memory.
+
+Check a query's pruning with `EXPLAIN indexes = 1 SELECT ...`: compare `Granules: selected/total` for the primary key. A query that selects most granules needs a different key, a projection, or a skip index.
+
+## 2. Partitions
+
+- Partitioning is for **data management** (dropping or moving old data, TTL), not for speed.
+- Use a coarse key, usually `PARTITION BY toYYYYMM(ts)`, or none at all for small tables. Keep the number of partitions well under about 1000.
+- Never partition by a high-cardinality column (user ID, raw timestamp, day across many years): every insert touching many partitions creates many parts and ends in `Too many parts` errors.
+- Expire data with `TTL ts + INTERVAL 90 DAY`; whole expired partitions are dropped cheaply, especially with `ttl_only_drop_parts = 1`.
+
+## 3. Inserts
+
+- Insert in **batches of at least 1,000 rows, ideally 10,000 to 100,000**, at about one insert per second per table or less. Each insert creates at least one part per partition it touches.
+- When many clients send small writes (events from apps, logs), enable server-side buffering instead of building a batcher: `SETTINGS async_insert = 1, wait_for_async_insert = 1`. Keep `wait_for_async_insert = 1` so errors reach the client.
+- Inserts are retried safely when the same block is resent to a replicated or Cloud table: identical blocks are deduplicated. Keep retries byte-identical (same rows, same order).
+- Use the native or RowBinary formats from drivers for throughput; JSONEachRow is fine for moderate volumes.
+- Watch part counts: `SELECT table, partition, count() FROM system.parts WHERE active GROUP BY table, partition ORDER BY count() DESC`. Hundreds of active parts in one partition means inserts are too small or too spread out.
+
+## 4. Column types
+
+- Use the smallest type that fits (`UInt32` not `Int64` for counts, `Date` when you don't need time, `DateTime64(3)` for milliseconds).
+- `LowCardinality(String)` for strings with fewer than about 10,000 distinct values (country, status, event name).
+- Avoid `Nullable` unless "unknown" is different from a default; it adds a hidden column and slows queries. Use `DEFAULT` values.
+- Use `Decimal` for money. Add codecs (`CODEC(Delta, ZSTD)` for monotonic timestamps and counters) only after checking `system.columns` compression ratios.
+- Use `Map`, `Tuple`, `JSON` or a `String` column with JSON functions for semi-structured data, and pull hot fields into real columns (`MATERIALIZED JSONExtractString(raw, 'path')`).
+
+## 5. Query optimisation
+
+1. Find the slow queries:
+   ```sql
+   SELECT query, query_duration_ms, read_rows, formatReadableSize(read_bytes) AS read, memory_usage
+   FROM system.query_log
+   WHERE type = 'QueryFinish' AND event_time > now() - INTERVAL 1 DAY
+   ORDER BY read_bytes DESC LIMIT 20
+   ```
+2. Read fewer columns: never `SELECT *` in production queries.
+3. Filter on sorting-key columns, in key order. ClickHouse moves selective filters to `PREWHERE` on its own; check with `EXPLAIN`.
+4. For a second access path, add a **projection** (`ALTER TABLE t ADD PROJECTION p (SELECT * ORDER BY user_id)`, then `ALTER TABLE t MATERIALIZE PROJECTION p` to build it for existing parts; that is a mutation, so ask first on production) or a materialised view into a table with a different key. For needle-in-haystack filters, a skip index (`INDEX idx col TYPE bloom_filter GRANULARITY 4`) can help; prove it with `EXPLAIN indexes = 1`.
+5. Joins: put the smaller table on the right side, filter both sides before joining, and use dictionaries (`dictGet`) for dimension lookups.
+6. Use `uniq` instead of `uniqExact` and `quantile` instead of `quantileExact` when approximate is acceptable; say so to the user.
+7. Pre-aggregate dashboards with a materialised view (section 6) instead of scanning raw events on every page load.
+
+## 6. Materialised views and rollups
+
+- An **incremental** materialised view (`CREATE MATERIALIZED VIEW mv TO target AS SELECT ...`) is an insert trigger: it processes only blocks inserted into the source after it is created. It does **not** see existing rows; backfill them with an explicit `INSERT INTO target SELECT ...`.
+- Always use `TO <target table>` so you control the target's engine, key and TTL.
+- Rollups into `SummingMergeTree` or `AggregatingMergeTree` are merged in the background, so rows for one key may exist several times. Queries must still aggregate (`sum(...)`, `uniqMerge(...)` with `GROUP BY`).
+- A **refreshable** materialised view (`REFRESH EVERY 1 HOUR`) re-runs a full query on a schedule; use it for joins and heavy reports where incremental logic is wrong.
+- `ReplacingMergeTree` deduplicates rows with the same sorting key only during merges, at an unknown time. Read with `FINAL` or `argMax(..., version)` per key when you need the latest row.
+
+## Never
+
+- Insert one row per request without async inserts.
+- Use `ALTER TABLE ... UPDATE` as a normal write path; model changes as new rows (ReplacingMergeTree, versioned rows) or use lightweight `DELETE FROM` sparingly.
+- Run `OPTIMIZE TABLE ... FINAL` on a schedule to "fix" duplicates; fix the query instead.
+- Claim a speedup without `read_rows` and `query_duration_ms` before and after.
+
+## Report format (when reviewing)
+
+```
+ClickHouse review: <tables or queries>
+Deployment/version: <Cloud | single | replicated>, <version>
+Findings:
+1. [severity] <table or file:line>: <problem> → <fix>
+Evidence: <query> read_rows / granules selected / duration, before → after
+Not verified: <anything you could not run>
+```

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

@@ -0,0 +1,18 @@
+{
+  "should_trigger": [
+    "Design a ClickHouse table for page view events, what ORDER BY and PARTITION BY should it have?",
+    "We get DB::Exception Too many parts when our services insert into ClickHouse",
+    "My ClickHouse materialized view doesn't include the rows that were already in the table",
+    "ReplacingMergeTree still shows duplicate rows, how do I query only the latest version?",
+    "This ClickHouse dashboard query reads 2 billion rows, help me make it faster",
+    "Build a daily rollup of events per tenant with AggregatingMergeTree and uniqState"
+  ],
+  "should_not_trigger": [
+    "Our Postgres reporting query is slow, should we add a BRIN index on created_at?",
+    "Write a MongoDB aggregation pipeline that groups orders by customer",
+    "Set up a Redis sorted set leaderboard for the game",
+    "Model order events in the Prisma schema and generate the client",
+    "Build a Grafana dashboard for our API latency metrics",
+    "Benchmark two implementations of our JSON parser fairly"
+  ]
+}

package/skills/clickhouse-patterns/references/engines-and-views.md

@@ -0,0 +1,138 @@
+# ClickHouse engines and materialised view recipes
+
+Read this when choosing an engine, writing a rollup, or deduplicating. Check syntax against clickhouse.com/docs for the server version in use. On ClickHouse Cloud, write the plain engine name (`MergeTree`, `ReplacingMergeTree`); the service maps it to its shared engine. On a self-hosted cluster, use the `Replicated*` variant with the `ON CLUSTER` conventions the existing tables use.
+
+## Choosing an engine
+
+| Engine | Merges rows with the same sorting key by | Use for |
+|---|---|---|
+| `MergeTree` | nothing (keeps all rows) | raw events, logs, append-only facts |
+| `ReplacingMergeTree(version)` | keeping the row with the highest `version` (or the last inserted) | latest state per entity, upserts, CDC from OLTP |
+| `SummingMergeTree` | summing numeric columns | simple counters per key |
+| `AggregatingMergeTree` | merging `AggregateFunction` states | rollups with `uniq`, `quantile`, `avg` |
+| `CollapsingMergeTree(sign)` / `VersionedCollapsingMergeTree` | cancelling `+1`/`-1` row pairs | changing aggregates with explicit cancel rows |
+
+All merging is eventual. Queries must be correct before merges happen.
+
+## Raw events table
+
+```sql
+CREATE TABLE analytics.events
+(
+    tenant_id   UInt32,
+    event_type  LowCardinality(String),
+    ts          DateTime64(3),
+    user_id     UInt64,
+    session_id  String,
+    props       String CODEC(ZSTD(3))
+)
+ENGINE = MergeTree
+PARTITION BY toYYYYMM(ts)
+ORDER BY (tenant_id, event_type, toDate(ts), user_id)
+TTL toDateTime(ts) + INTERVAL 13 MONTH
+SETTINGS ttl_only_drop_parts = 1;
+```
+
+## Latest state with ReplacingMergeTree
+
+```sql
+CREATE TABLE app.users_latest
+(
+    user_id    UInt64,
+    email      String,
+    plan       LowCardinality(String),
+    updated_at DateTime64(3),
+    is_deleted UInt8 DEFAULT 0
+)
+ENGINE = ReplacingMergeTree(updated_at)
+ORDER BY user_id;
+```
+
+Read the current state either way:
+
+```sql
+SELECT * FROM app.users_latest FINAL WHERE is_deleted = 0;
+
+SELECT user_id, argMax(plan, updated_at) AS plan
+FROM app.users_latest
+GROUP BY user_id;
+```
+
+`FINAL` is much cheaper on recent versions than it used to be, but still costs more than a plain read; measure it. Newer versions also accept an `is_deleted` column as a second engine parameter; check the docs for your version before relying on it.
+
+## Daily rollup with AggregatingMergeTree
+
+```sql
+CREATE TABLE analytics.daily_events
+(
+    tenant_id  UInt32,
+    day        Date,
+    event_type LowCardinality(String),
+    events     SimpleAggregateFunction(sum, UInt64),
+    users      AggregateFunction(uniq, UInt64)
+)
+ENGINE = AggregatingMergeTree
+PARTITION BY toYYYYMM(day)
+ORDER BY (tenant_id, day, event_type);
+
+CREATE MATERIALIZED VIEW analytics.daily_events_mv TO analytics.daily_events AS
+SELECT tenant_id, toDate(ts) AS day, event_type,
+       count() AS events,
+       uniqState(user_id) AS users
+FROM analytics.events
+GROUP BY tenant_id, day, event_type;
+```
+
+Query it with merge functions, always grouping:
+
+```sql
+SELECT day, sum(events) AS events, uniqMerge(users) AS users
+FROM analytics.daily_events
+WHERE tenant_id = 42 AND day >= today() - 30
+GROUP BY day ORDER BY day;
+```
+
+Backfill existing data once, in chunks by partition, with the same SELECT as the view:
+
+```sql
+INSERT INTO analytics.daily_events
+SELECT tenant_id, toDate(ts) AS day, event_type, count(), uniqState(user_id)
+FROM analytics.events
+WHERE toYYYYMM(ts) = 202609
+GROUP BY tenant_id, day, event_type;
+```
+
+To avoid double counting, create the view first, note the time, and backfill only rows before it, or pause ingestion during the switch.
+
+## Materialised view gotchas
+
+- The view's SELECT runs on each inserted **block**, not on the whole table. A `GROUP BY` in it aggregates within the block only; the target engine finishes the job.
+- A failing view makes the insert into the source fail. Test the view's SELECT on sample data first.
+- Joins inside an incremental view read the right-hand table at insert time; later changes to it don't update old rows. Use a dictionary or a refreshable view instead.
+- Changing a view: create the new target and view, backfill, switch readers, then drop the old ones.
+
+## Refreshable view
+
+```sql
+CREATE MATERIALIZED VIEW reports.top_customers
+REFRESH EVERY 1 HOUR
+ENGINE = MergeTree ORDER BY revenue
+AS SELECT customer_id, sum(amount) AS revenue
+FROM sales.orders
+GROUP BY customer_id
+ORDER BY revenue DESC
+LIMIT 100;
+```
+
+Each refresh replaces the content atomically. Check status in `system.view_refreshes`.
+
+## Useful system tables
+
+| Table | Use |
+|---|---|
+| `system.query_log` | slow and heavy queries, `read_rows`, `memory_usage` |
+| `system.parts` | active part counts and sizes per partition |
+| `system.merges` | merges in progress |
+| `system.mutations` | `ALTER ... UPDATE/DELETE` progress (`is_done`) |
+| `system.columns` | compressed vs uncompressed size per column |
+| `system.replication_queue` | replicated table backlogs (self-hosted) |

package/skills/clinical-decision-support/SKILL.md

@@ -0,0 +1,90 @@
+---
+name: clinical-decision-support
+description: Engineering discipline for software that recommends or warns at the point of care, including CDS Hooks services (discovery, patient-view and order-sign hooks, prefetch, cards, suggestions, feedback), alert design that avoids alert fatigue, versioned rule logic tied to cited evidence, clinician sign-off and regression testing on synthetic cases, override and audit trails, and the regulatory line where software becomes a medical device (FDA CDS guidance, EU MDR Rule 11, UK DCB0129). Use when building drug-interaction or dosing alerts, risk scores, care-gap reminders or AI suggestions shown to clinicians, writing a CDS Hooks service, or deciding whether a clinical feature needs regulatory or clinical-safety review.
+license: MIT
+compatibility: Any Agent Skills host. Works on any codebase; CDS Hooks testing needs a FHIR sandbox or the CDS Hooks sandbox. Regulatory statements must be checked against current FDA, EU and national guidance by a qualified person.
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: compliance
+  kete-loom/risk: writes-files
+  kete-loom/owner: "Kete-org"
+---
+
+# Clinical decision support
+
+Build decision support that clinicians trust: it fires rarely and correctly, shows its reasoning and evidence, can be overridden with a reason, is traceable to a reviewed rule version, and stays on the right side of medical device regulation.
+
+## Boundary: not clinical, legal or regulatory advice
+
+- You engineer the system. You never author or approve clinical content (thresholds, doses, interactions, risk cut-offs). A named clinician owns every rule and signs off each version.
+- You never decide whether the product is a regulated medical device. You flag the questions; regulatory affairs or counsel decides.
+- Say this once, plainly, when the user asks for clinical thresholds or a regulatory verdict, then continue with the engineering. Never invent a clinical threshold to fill a gap; leave a named placeholder and stop.
+
+## Step 1: classify the feature before building
+
+Answer these and write the answers into the design doc:
+
+1. **Who sees it?** A healthcare professional, a patient or caregiver, or nobody (automatic action)?
+2. **What does it do?** Display reference information, flag something for review, recommend one action, or take an action automatically?
+3. **What are the inputs?** Structured data and published guidelines, or medical images, signals (ECG, waveforms) or IVD data?
+4. **Can the clinician independently review the basis?** Are the inputs, logic and evidence shown so they need not rely on the software alone?
+5. **Is it time-critical?** Would a clinician have time to review the basis before acting?
+
+Then apply the regulatory flags in `references/regulatory-boundaries.md`. If the feature analyses images or signals, targets patients directly, acts automatically, is opaque (for example an ML model whose basis the clinician cannot review), or is used in time-critical decisions, **stop and tell the user it needs regulatory review before build**.
+
+## Step 2: design the intervention
+
+- **Fire only when actionable.** Every alert names one specific patient, finding and action. If nobody can act on it right now, it is not an interruptive alert: make it passive (a chart flag, a worklist, `info` card) or drop it.
+- **Right time, right person.** Trigger at the workflow step where the decision is made (for drug checks: `order-select` or `order-sign`, not `patient-view`). Target the role that can act.
+- **Severity is earned.** Reserve interruptive or `critical` for harm that is likely and serious. Tier everything else. Track the override rate per rule; a rule overridden most of the time is noise and needs clinical review.
+- **Show the why.** Include the triggering data (values, dates), the rule's logic in plain words, and a link to the evidence source.
+- **Make the right action one click.** Offer a concrete suggestion (adjust dose, order test, discontinue) and allow override with a structured reason.
+- **Suppress duplicates.** Don't re-fire the same alert for the same patient and data in one session; respect snoozes and documented exceptions.
+- **Fail safe and visible.** If the CDS service is down or data is missing, show nothing interruptive but never imply "no issues found". Missing inputs must not be treated as normal values.
+
+## Step 3: build the logic as versioned, reviewable artefacts
+
+- Keep rules in data or a dedicated module (for example CQL libraries, or a rules table), not scattered through UI code.
+- Each rule has: ID, semantic version, owner clinician, evidence citation (guideline, version, date), inputs with code systems (LOINC, SNOMED CT, RxNorm), logic, outputs, effective date, review-by date.
+- Units and codes are explicit. Convert units with a library (UCUM), never assume. Handle `preliminary`, `corrected` and `entered-in-error` source data.
+- Every change goes through code review **and** clinical review, and bumps the rule version. Record who approved and when.
+
+## Step 4: implement the delivery
+
+For EHR-embedded CDS use CDS Hooks as in `references/cds-hooks.md`: a discovery endpoint, one service per hook, prefetch templates for the data you need, cards with `summary`, `indicator`, `source` and suggestions, and the feedback endpoint to capture accept/override. Authenticate the EHR's JWT on every call and use the `fhirAuthorization` token only for the patient in context.
+
+## Step 5: test with clinicians
+
+1. Build a test set of synthetic patients (never real records) per rule: must fire, must not fire, boundary values, missing data, unit variants, corrected results, duplicate orders.
+2. Store expected outputs and run them as automated regression tests on every change.
+3. A clinician reviews the cases and the card wording before release and signs the test report.
+4. Pilot silently first where possible ("shadow mode": evaluate and log, don't show) and compare fire rates with expectations.
+
+## Step 6: audit and monitor
+
+Log, for every evaluation that produced output: timestamp, rule ID and version, patient reference (internal ID, not name), user, hook instance, card shown, action taken, override reason. Keep it append-only and access-controlled like other PHI logs (`hipaa-compliance`). Review override rates, fire rates and reported incidents on a schedule, and give clinicians a way to report a bad alert.
+
+## Stop and ask the user
+
+- Before writing any clinical threshold, dose, interaction or score cut-off: ask who the clinical owner is and for the source.
+- When Step 1 raises a regulatory flag.
+- Before making any alert interruptive, or any action automatic.
+- Before shipping a rule change without recorded clinical sign-off.
+
+## Never
+
+- Never auto-order, auto-cancel or auto-change medication or orders without explicit clinical governance approval.
+- Never hide the inputs or reasoning behind a recommendation.
+- Never treat missing data as normal.
+- Never ship ML-based suggestions as if they were rule-based, or without documented validation on the target population.
+- Never let a CDS outage silently disable safety checks without telling users.
+
+## Report format
+
+```
+Feature: <name>, audience, hook or trigger point
+Classification: <answers to Step 1>, regulatory flags: <none | list → needs regulatory review>
+Rules: <ID@version, owner, evidence source> per rule
+Test coverage: <cases per rule, clinician sign-off status>
+Open items for clinical/regulatory owners: <list>
+```

package/skills/clinical-decision-support/evals/triggers.json

@@ -0,0 +1,16 @@
+{
+  "should_trigger": [
+    "Build a CDS Hooks service that warns at order-sign when a renally cleared drug is ordered for a patient with low eGFR",
+    "Our sepsis alert fires constantly and nurses override 95% of them, how should we redesign it?",
+    "Does our symptom checker that recommends a diagnosis to patients count as a medical device under FDA rules?",
+    "Set up versioning, clinician sign-off and regression tests for our medication dosing rules",
+    "How do we audit which decision support cards were shown, accepted or overridden by each clinician?"
+  ],
+  "should_not_trigger": [
+    "Fetch MedicationRequest resources from the EHR's FHIR API with a SMART standalone launch",
+    "Parse ORU^R01 lab results arriving over MLLP and send an ACK",
+    "Which HIPAA safeguards does our telehealth backend need for video visits?",
+    "Train a gradient boosting model to predict readmission and report its AUC",
+    "Review the clinic scheduling service for PHI in logs and missing consent checks"
+  ]
+}

package/skills/clinical-decision-support/references/cds-hooks.md

@@ -0,0 +1,76 @@
+# CDS Hooks implementation notes
+
+Source: CDS Hooks specification 2.0 (cds-hooks.hl7.org, STU 2, based on FHIR R4). Check the EHR vendor's docs for which hooks and features they support.
+
+## Endpoints
+
+| Endpoint | Purpose |
+|---|---|
+| `GET {base}/cds-services` | discovery: list of services with `hook`, `id`, `title`, `description`, `prefetch`, optional `usageRequirements` |
+| `POST {base}/cds-services/{id}` | invoke a service for a hook |
+| `POST {base}/cds-services/{id}/feedback` | the EHR reports which cards and suggestions were accepted or overridden |
+
+## Standard hooks
+
+`patient-view`, `order-select`, `order-sign`, `order-dispatch`, `appointment-book`, `encounter-start`, `encounter-discharge`, `medication-refill`, `allergyintolerance-create`, `problem-list-item-create`. (`medication-prescribe` and `order-review` are deprecated.) Each hook defines its `context` fields, for example `order-sign` carries `userId`, `patientId`, `encounterId` and `draftOrders` (a Bundle).
+
+## Discovery example
+
+```json
+{
+  "services": [{
+    "hook": "order-sign",
+    "id": "renal-dose-check",
+    "title": "Renal dose check",
+    "description": "Flags renally cleared drugs ordered for patients with reduced eGFR",
+    "prefetch": {
+      "patient": "Patient/{{context.patientId}}",
+      "egfr": "Observation?patient={{context.patientId}}&code=http://loinc.org|<egfr-code>&_sort=-date&_count=1"
+    }
+  }]
+}
+```
+
+Prefetch is an optimisation the EHR may skip: if a key is missing, fetch it from `fhirServer` with `fhirAuthorization.access_token`, and if neither is available return no cards rather than guessing. Log that the check could not run and count it, so an outage shows up in monitoring instead of looking like "no issues".
+
+## Request fields
+
+`hook`, `hookInstance` (UUID, use it as the correlation ID in audit logs), `fhirServer`, `fhirAuthorization` (`access_token`, `token_type`, `expires_in`, `scope`, `subject`), `context`, `prefetch`.
+
+## Security
+
+- The EHR sends a signed JWT bearer token in `Authorization`. Verify it on every request: signature against the EHR's JWK Set (from the optional `jku` header only if that URL is on your allowlist, otherwise a key exchanged out of band), `iss` on your allowlist of EHRs, `aud` equal to the URL of the endpoint being called (`{base}/cds-services/{id}`), `exp` not passed, `iat` present, `jti` not replayed.
+- Use the `fhirAuthorization` token only for the patient in context and discard it after the call.
+- Never log `prefetch` or `context` bodies; log `hookInstance`, service ID, rule versions and card UUIDs.
+
+## Response
+
+```json
+{
+  "cards": [{
+    "uuid": "6f0c...",
+    "summary": "Dose may be too high for eGFR 25 (under 140 chars)",
+    "detail": "Markdown: triggering values, the rule in plain words, evidence link",
+    "indicator": "warning",
+    "source": { "label": "Renal dosing rules v1.4.0", "url": "https://example.org/evidence" },
+    "suggestions": [{ "label": "Reduce dose", "uuid": "...", "isRecommended": true, "actions": [{ "type": "update", "description": "...", "resource": {} }] }],
+    "selectionBehavior": "at-most-one",
+    "overrideReasons": [{ "code": "benefit-outweighs-risk", "system": "https://example.org/override-reasons", "display": "Benefit outweighs risk" }],
+    "links": [{ "label": "Guideline", "url": "https://...", "type": "absolute" }]
+  }],
+  "systemActions": []
+}
+```
+
+- `indicator`: `info`, `warning`, `critical` (increasing urgency).
+- `selectionBehavior` is required when `suggestions` is present.
+- `systemActions` are applied by the EHR without showing the user: leave empty unless clinical governance has approved the automation.
+- Return `{"cards": []}` when nothing applies. Respond fast (the clinician is waiting); set a timeout budget well under the EHR's.
+
+## Feedback
+
+Give every card and suggestion a `uuid`: the EHR sends no feedback for a card or suggestion without one. Store each feedback item (`card`, `outcome` accepted/overridden, `acceptedSuggestions`, `overrideReason`, `outcomeTimestamp`) against the rule version. This is the data for override-rate and alert-fatigue review.
+
+## Testing
+
+The public CDS Hooks sandbox (sandbox.cds-hooks.org) can call a service you host and render its cards. Use synthetic patients only.