@ketecode/loom 0.0.0-stage → 0.1.0

package/skills/browser-qa/SKILL.md

@@ -0,0 +1,99 @@
+---
+name: browser-qa
+description: Exploratory, manual-style QA session on a running web app through a real browser, walking the critical user journeys, abusing forms and validation, spot-checking small screens, keyboard use and contrast, and watching the console and network panel, then filing reproducible bug reports. Use when someone wants a site or staging build clicked through and checked before a release, demo or handover, rather than automated tests written.
+license: MIT
+compatibility: Any Agent Skills host with a browser-control capability (a browser automation tool or MCP server). Without one, produce the test plan and ask the user to run it.
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: testing
+  kete-loom/risk: runs-commands
+  kete-loom/owner: "Kete-org"
+---
+
+# Browser QA pass
+
+Act as a careful human tester. You are looking for what a real user would hit, and you prove each problem with exact steps. You do not write automated tests here; if the user wants those, use the `e2e-testing-playwright` skill instead.
+
+## 0. Agree the scope
+
+Before opening the browser, confirm:
+
+1. **The URL** and the environment (local, staging, preview). **Never test against production** with real data or payments unless the user says so explicitly in this conversation.
+2. **Test accounts** and roles. Don't sign up with a real person's email or phone number. If you need an account and have none, **stop and ask**.
+3. **What changed** or what matters most, if anything. Weight the pass toward it.
+4. **What is off limits**: sending emails or SMS, real payments, deleting shared data. When an action would have an external effect you weren't cleared for, stop and ask.
+
+If you have no way to control a browser, write the checklist from steps 1 to 5 and hand it to the user.
+
+## 1. Map the critical journeys
+
+List 3 to 7 journeys from the navigation, the README or the user: for example sign up, log in, log out, password reset, search, create/edit/delete the core object, checkout. Do them first, end to end, on a desktop-size window. Note every journey you could not complete and why.
+
+## 2. Forms and validation
+
+For each important form:
+
+- Submit empty. Each required field should show a clear message tied to that field.
+- Wrong formats: bad email, letters in a number, a date in the past where only future dates make sense, an amount of 0 and a negative one.
+- Boundaries: very long text (500+ characters), emoji and non-Latin text (`Kwame Nkrumah`, `Ɔkɔmfo`, `Zoë`, `日本`), leading and trailing spaces, pasted text.
+- Double submit: click the submit button twice quickly. Exactly one record or charge should result.
+- Server errors: does a failed request show a helpful message and keep what the user typed?
+- Navigation: back button after submit, refresh mid-flow, opening the same flow in two tabs.
+
+## 3. Responsive spot check
+
+Resize to about 375 px wide (phone), 768 px (tablet) and 1280 px (desktop), or use device emulation. On each: no horizontal scrolling, nothing cut off, menus open and close, tap targets are not crammed together, modals fit and can be closed.
+
+## 4. Accessibility spot check
+
+This is a quick screen, not an audit:
+
+- Tab through each journey with the keyboard only. Focus is visible, the order makes sense, nothing traps focus, and Escape closes dialogs.
+- Every input has a visible label; icon-only buttons have an accessible name.
+- Images that carry meaning have alt text.
+- Text contrast looks sufficient, and information is not conveyed by colour alone.
+- Zoom to 200 %: content still usable.
+
+For a full WCAG review, recommend the `accessibility-reviewer` agent or the `web-accessibility` skill.
+
+## 5. Console and network
+
+Keep the console and network log open during every journey.
+
+- Console: uncaught errors, failed hydration, React or Vue warnings, CSP violations, mixed-content warnings.
+- Network: any 4xx or 5xx, requests that take more than a couple of seconds, duplicate requests for the same thing, secrets or personal data in URLs or responses that shouldn't be there.
+- Note which user action produced each one.
+
+## 6. Verify before you report
+
+For each issue: reproduce it a second time from a fresh page load. If it doesn't reproduce, report it as intermittent with what you observed, not as a confirmed bug. Check it isn't caused by your own test data or an expired session.
+
+## Bug report format
+
+One block per bug:
+
+```
+### BUG-<n>: <short title stating the wrong behaviour>
+Severity: blocker | major | minor | cosmetic
+Where: <URL or screen>, <browser and window size>, <account/role>
+Steps:
+  1. ...
+  2. ...
+Expected: ...
+Actual: ...
+Evidence: <console error text, failing request + status, screenshot name>
+Reproduced: 2/2 | intermittent (1/3)
+```
+
+Severity guide: **blocker** stops a critical journey or loses data or money; **major** breaks a feature but has a workaround; **minor** is wrong but low impact; **cosmetic** is visual only.
+
+## Final summary
+
+End with:
+
+1. Environment, browser and build tested, and the time.
+2. A table of journeys with pass / fail / not tested.
+3. Bugs ordered by severity (the blocks above).
+4. What you did not cover (browsers, roles, screens, payments), stated plainly.
+
+Never call a build "ready to ship"; report what you saw and let the user decide.

package/skills/browser-qa/evals/triggers.json

@@ -0,0 +1,16 @@
+{
+  "should_trigger": [
+    "Can you click through our staging site and find bugs before tomorrow's launch?",
+    "Do a QA pass on the signup and checkout pages at localhost:5173 and write up anything broken",
+    "Smoke test the new dashboard in the browser on mobile and desktop sizes",
+    "Go through the app like a real user and tell me if the forms handle bad input properly",
+    "Check the preview deploy for console errors and failed requests while you use it"
+  ],
+  "should_not_trigger": [
+    "Write Playwright specs for the login and checkout flows",
+    "Do a full WCAG 2.2 accessibility review of our component library",
+    "Our e2e suite is flaky on CI, find out why and fix it",
+    "Measure our Largest Contentful Paint and suggest how to bring it down",
+    "Review the tests added in PR 482 for weak assertions"
+  ]
+}

package/skills/bun-runtime/SKILL.md

@@ -0,0 +1,93 @@
+---
+name: bun-runtime
+description: Working with Bun as a JavaScript runtime, package manager, test runner and bundler, and knowing where it differs from Node and npm, including bun.lock and trustedDependencies, bunfig.toml, bun test with bun:test mocks, bun build and --compile, Bun.serve, automatic .env loading, Node API compatibility gaps, and when to stay on Node. Use when adopting or migrating to Bun, debugging something that works on Node but fails under Bun, setting up bun test or bun install in CI, or deciding whether Bun is a safe choice for a project.
+license: MIT
+compatibility: Any Agent Skills host. Needs the bun CLI. Bun changes quickly; confirm version-specific behaviour against bun.com/docs for the installed version (bun --version).
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: coding
+  kete-loom/risk: runs-commands
+  kete-loom/requires: "bun"
+  kete-loom/owner: "Kete-org"
+---
+
+# Bun runtime
+
+Bun is four tools in one binary: a runtime (JavaScriptCore, not V8), a package manager, a test runner and a bundler. A project can adopt any of them separately. Decide which ones you are using before changing anything.
+
+## First, look at the project
+
+1. Run `bun --version` and read `package.json`, `bunfig.toml` (if any) and the lockfile name: `bun.lock` (text, Bun 1.2+), `bun.lockb` (older binary format), or another manager's lockfile.
+2. Note what runs in production: Bun, Node, or a serverless platform. The deploy target decides which Bun APIs are safe to use.
+3. Search the code for `Bun.`, `bun:` imports and native addons (`.node` files, `node-gyp`, `prebuild` in dependencies).
+
+Stop and ask the user before switching the production runtime from Node to Bun, or replacing the project's package manager, test runner or bundler. Each is a separate decision.
+
+## Package manager
+
+- `bun install` reads `package.json` and writes `bun.lock`. Commit it; delete other managers' lockfiles only when the team has agreed to switch.
+- Convert an old `bun.lockb` with `bun install --save-text-lockfile --frozen-lockfile --lockfile-only`, then remove `bun.lockb`.
+- CI: `bun install --frozen-lockfile` (or `bun ci`). Bun does not enable frozen mode automatically in CI.
+- **Lifecycle scripts of dependencies do not run** unless the package is listed in `trustedDependencies` in `package.json`. A package that needs a `postinstall` (native builds, binary downloads such as some image, database or browser packages) often fails later at runtime instead of during install. Add it to `trustedDependencies` deliberately and reinstall; never trust everything blindly.
+- Linker: workspaces created on recent Bun default to the `isolated` layout (pnpm-like, no phantom dependencies); single packages and older projects default to `hoisted`. Code that imports an undeclared transitive dependency breaks under `isolated`: declare the dependency rather than switching linker.
+- `bunx <pkg>` is the `npx` equivalent. `bun run <script>` runs `package.json` scripts; CLIs with a `#!/usr/bin/env node` shebang (vite, next) still run under Node unless you use `bun run --bun <script>`.
+
+## Runtime differences from Node
+
+- **TypeScript and JSX run directly** with no build step, but **Bun does not type-check**. Keep `tsc --noEmit` in the check pipeline.
+- **`.env` is loaded automatically** (`.env`, then `.env.<NODE_ENV>`, `.env.local` (skipped when `NODE_ENV=test`), `.env.<NODE_ENV>.local`). This can surprise tools that load env themselves (Vite warns about it) and can leak local values into tests. Use `--env-file <path>` to choose files, or `--no-env-file` / `env = false` in `bunfig.toml` to turn it off.
+- ESM and CommonJS can be mixed in one file, and `require` of ESM works. Code that relies on this will not run on Node; keep shared libraries Node-compatible.
+- Bun-only APIs: `Bun.serve`, `Bun.file`, `Bun.write`, `Bun.spawn`, `Bun.password`, `bun:sqlite`, `bun:ffi`. Use them only in code that will never run on Node; otherwise use `node:` modules.
+- Native addons: N-API addons generally work; addons that use V8's C++ API directly do not, because there is no V8.
+- `Bun.serve({ fetch(req) { ... } })` uses web `Request`/`Response`. Express and Fastify also run on Bun through its `node:http` implementation; benchmark before assuming a speed-up for your workload.
+
+## Known Node compatibility gaps
+
+Bun publishes a per-module compatibility page (bun.com/docs/runtime/nodejs-compat). Check it for the installed version before relying on any of these. Gaps that commonly matter:
+
+| Area | What breaks |
+|---|---|
+| `async_hooks.createHook` | Stubbed; APM/tracing agents that depend on it lose context. `AsyncLocalStorage` itself works. |
+| `node:v8`, `node:inspector` | Partial: `v8.serialize` uses JavaScriptCore's format, and the inspector covers only some domains. Profilers and heap tools written for V8 may not work. |
+| `node:crypto` | Partial: Bun uses BoringSSL, so some algorithms and APIs are missing. Test the exact algorithm you need on Bun. |
+| `node:cluster` | Partial: HTTP servers in workers each bind their own socket, so do not assume Node's load balancing. |
+| `node:test` | Partial: works only when files run under `bun test`; prefer `bun:test`. |
+| `node:sea` | Not supported; use `bun build --compile`. |
+
+When something works on Node but fails on Bun: reproduce with a minimal script on both, check the compatibility page and Bun's issue tracker, then either work around it or keep that piece on Node. Never patch `node_modules`.
+
+## bun test
+
+- Discovers `*.test.*`, `*_test.*`, `*.spec.*`, `*_spec.*`. Import from `bun:test`: `test`, `describe`, `expect`, `beforeEach`, `mock`, `spyOn`.
+- Jest-compatible but not complete: `jest.fn()` works, `mock.module('pkg', () => ({ ... }))` replaces a module, but some Jest matchers and config options are missing. When migrating, run the whole suite and fix gaps one by one; do not mix Jest and `bun test` on the same files.
+- Setup files: `bun test --preload ./test/setup.ts`, or `[test] preload = ["./test/setup.ts"]` in `bunfig.toml`. DOM tests need a preload that registers happy-dom (`@happy-dom/global-registrator`).
+- Useful flags: `--watch`, `--coverage` (`--coverage-reporter=lcov` for CI), `--timeout <ms>` (default 5000), `-u` to update snapshots, `--bail`.
+- Bun runs test files in a single process by default: tests that mutate globals, env or `mock.module` state leak into other files. Restore mocks in `afterEach`, or pass `--parallel` to spread files across CPU cores (check that your Bun version has this flag).
+
+## bun build
+
+- `bun build ./src/index.ts --outdir dist --target node|bun|browser`. Add `--minify`, `--sourcemap=linked`, `--splitting`, `--external <pkg>` as needed. JS API: `await Bun.build({ entrypoints, outdir, target })`.
+- It does not emit `.d.ts` files; libraries still need `tsc --emitDeclarationOnly`.
+- `bun build --compile ./src/cli.ts --outfile mycli` makes a standalone executable with the runtime embedded (large binary, but no install step for users).
+- For browser apps with HMR, dev server and framework plugins, a dedicated tool (Vite, see the `vite-patterns` skill) is usually the better fit.
+
+## When not to use Bun
+
+Recommend staying on Node (or keeping Node in production while using Bun for install/test) when:
+
+- The service depends on an APM, profiler or tracing agent that needs V8 or `async_hooks` hooks.
+- It uses native addons built against V8, or crypto primitives BoringSSL lacks.
+- The hosting platform has no first-class Bun runtime and a custom runtime is not acceptable to the team.
+- The team needs long-term-support guarantees comparable to Node LTS.
+- A library the project depends on documents Bun as unsupported.
+
+## Never
+
+- Commit both `bun.lock` and another manager's lockfile as sources of truth.
+- Add every dependency to `trustedDependencies` to make an install error go away.
+- Use `Bun.*` APIs in a package published for Node users.
+- Drop `tsc` because "Bun runs TypeScript".
+
+## Report
+
+When asked to evaluate or migrate, return: what was switched (runtime / package manager / tests / bundler), commands now used for install, test, build and start, any compatibility gap found and its workaround, and the test and type-check results on Bun.

package/skills/bun-runtime/evals/triggers.json

@@ -0,0 +1,16 @@
+{
+  "should_trigger": [
+    "Migrate our Jest suite to bun test and get mock.module working",
+    "This package's postinstall never ran after bun install, the native binary is missing",
+    "Is it safe to run our production API on Bun? We use Datadog tracing",
+    "Our app works on Node but crashes under Bun with a crypto curve error",
+    "Make a single-file executable of our CLI with bun build --compile"
+  ],
+  "should_not_trigger": [
+    "Add graceful shutdown and rate limiting to our Express service running on Node",
+    "Configure Vite library mode to publish our component package",
+    "Set up Vitest for our TypeScript utilities package",
+    "Write a GitHub Actions workflow that runs npm ci and the tests",
+    "Fix the circular dependency between two NestJS modules"
+  ]
+}

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"
+  ]
+}