@ketecode/loom 0.0.0-stage → 0.1.0

package/skills/ffmpeg-media-processing/SKILL.md

@@ -0,0 +1,94 @@
+---
+name: ffmpeg-media-processing
+description: FFmpeg and ffprobe command lines for audio and video work - transcoding with libx264, libx265, libvpx-vp9, AAC and Opus, choosing containers, stream copy versus re-encode, frame-accurate trimming, concat demuxer joins, scale and pad filters, burned-in or soft subtitles, thumbnails and contact sheets, HLS VOD ladders, NVENC, VideoToolbox, QSV and VAAPI hardware encoding, and calling ffmpeg safely from code with argument arrays. Use when writing or debugging an ffmpeg command, converting or compressing media files, cutting or joining clips, producing HLS segments, or running ffmpeg on user uploads in a backend.
+license: MIT
+compatibility: Any Agent Skills host. Needs ffmpeg and ffprobe on PATH; hardware encoders need a matching GPU, driver and an ffmpeg build that includes them.
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: coding
+  kete-loom/risk: runs-commands
+  kete-loom/requires: "ffmpeg, ffprobe"
+  kete-loom/owner: "Kete-org"
+---
+
+# FFmpeg media processing
+
+Probe first, decide copy or re-encode, write the smallest command that does it, then probe the output. Ready-made recipes are in `references/recipes.md`.
+
+## 0. Probe the input
+
+```bash
+ffprobe -v error -show_entries format=duration,bit_rate:stream=index,codec_type,codec_name,width,height,r_frame_rate,pix_fmt,channels,sample_rate -of json input.mp4
+```
+
+Record: container, video codec, resolution, frame rate (variable?), pixel format (10-bit `yuv420p10le`?), audio codec and channels, subtitle streams, duration. Check `ffmpeg -hide_banner -encoders | grep -E "264|265|vp9|av1|nvenc|videotoolbox|qsv|vaapi"` to see what this build can encode.
+
+## 1. Copy or re-encode
+
+| Situation | Do |
+|---|---|
+| Only changing the container (MKV to MP4) and codecs are allowed in the target | `-c copy` (seconds, no quality loss) |
+| Cutting on keyframes is fine | `-ss` before `-i` with `-c copy` |
+| Cutting must be frame-accurate, scaling, filters, burning subtitles | re-encode the video; audio can often still be `-c:a copy` |
+| Target must play everywhere (web, phones) | H.264 `-c:v libx264 -pix_fmt yuv420p` + AAC in MP4 with `-movflags +faststart` |
+| Smaller files, modern players | H.265 (`libx265`, add `-tag:v hvc1` for Apple players), VP9/Opus in WebM, or AV1 (`libsvtav1`) |
+
+Filters (`-vf`, `-af`, `-filter_complex`) never work with `-c copy` for that stream.
+
+## 2. Quality settings
+
+- x264/x265: control quality with `-crf` (x264: 18 visually near-lossless, 23 default, 28 small; x265 defaults to 28) and speed with `-preset` (`veryfast` ... `slow`). Use CRF for files, not a fixed bitrate, unless a target bitrate is required (streaming, size cap).
+- For a size cap use two-pass with `-b:v` (`-pass 1 -an -f null /dev/null`, then `-pass 2`).
+- VP9: `-c:v libvpx-vp9 -crf 31 -b:v 0` (the `-b:v 0` is what makes it constant quality).
+- Audio: `-c:a aac -b:a 128k`, or `-c:a libopus -b:a 96k` in WebM/MKV. Normalise loudness with `-af loudnorm=I=-16:TP=-1.5:LRA=11`.
+- Always `-pix_fmt yuv420p` for H.264 meant for browsers; 4:4:4 or 10-bit H.264 won't play in many of them.
+
+## 3. Common jobs
+
+- **Trim**: `ffmpeg -ss 00:01:00 -i in.mp4 -t 30 -c:v libx264 -crf 20 -c:a aac out.mp4`. `-ss` before `-i` seeks fast and is accurate when re-encoding; with `-c copy` the cut snaps to the previous keyframe. `-t` is a duration, `-to` an end time.
+- **Concatenate** files with identical codecs and settings: concat demuxer (`-f concat -safe 0 -i list.txt -c copy`). Different codecs or sizes: the `concat` filter in `-filter_complex` and re-encode. Recipe in `references/recipes.md`.
+- **Scale**: `-vf "scale=1280:-2"` (`-2` keeps aspect ratio with an even height). Fit into a box with letterboxing: `scale=1920:1080:force_original_aspect_ratio=decrease,pad=1920:1080:(ow-iw)/2:(oh-ih)/2`.
+- **Frame rate**: `-vf fps=30` (or `-r 30` on output). Variable frame rate phone video: re-encode with `fps=` to stop audio drift in editors.
+- **Audio only**: `-vn -c:a libmp3lame -q:a 2 out.mp3` or `-vn -c:a copy out.m4a` when the source is AAC.
+- **Subtitles**: burn in with `-vf "subtitles=subs.srt"` (needs libass, re-encodes); soft subs in MP4 with `-c:s mov_text`, in MKV with `-c:s srt` or `ass`. Map streams explicitly with `-map 0:v -map 0:a -map 1:s`.
+- **Thumbnail**: `ffmpeg -ss 10 -i in.mp4 -frames:v 1 -q:v 2 thumb.jpg`. One per 10 s: `-vf fps=1/10 thumb_%03d.jpg` (several frames need a numbered output pattern). Contact sheet of the first 16 samples: `-vf "fps=1/10,scale=320:-2,tile=4x4" -frames:v 1 sheet.jpg`.
+- **HLS**: see `references/recipes.md` for a single rendition and a multi-bitrate ladder with `-master_pl_name` and `-var_stream_map`.
+
+## 4. Hardware acceleration
+
+Use it when throughput matters more than size-for-quality; hardware encoders need a higher bitrate for the same quality as x264/x265.
+
+| Platform | Encode | Decode/filters |
+|---|---|---|
+| NVIDIA | `-c:v h264_nvenc` / `hevc_nvenc` with `-preset p1`..`p7` and `-cq` | `-hwaccel cuda -hwaccel_output_format cuda`, `scale_cuda` |
+| macOS | `-c:v h264_videotoolbox` / `hevc_videotoolbox` with `-b:v` or `-q:v` | `-hwaccel videotoolbox` |
+| Intel | `-c:v h264_qsv` / `hevc_qsv` with `-global_quality` | `-hwaccel qsv` |
+| Linux VAAPI | `-vaapi_device /dev/dri/renderD128 -vf 'format=nv12,hwupload' -c:v h264_vaapi` | `-hwaccel vaapi` |
+
+If a hardware encoder errors, check `ffmpeg -encoders` and the driver, then fall back to the software encoder rather than shipping a broken path. Mixing a hardware-decoded frame with a software filter needs `hwdownload,format=nv12`.
+
+## 5. Running ffmpeg from code
+
+1. **Pass an argument array, never a shell string.** `spawn('ffmpeg', ['-i', inputPath, ...])` in Node, `subprocess.run(['ffmpeg', ...], check=True)` in Python. No `shell=True`, no string interpolation of file names, titles or user text into a command line.
+2. **Generate the file names yourself** (UUIDs in a temp dir) and keep user names only as metadata. A user file name starting with `-` would otherwise be read as an option.
+3. **Treat uploads as hostile.** FFmpeg picks the demuxer from the file's content, not its extension, so an "mp4" upload can really be an HLS playlist or concat list that makes ffmpeg fetch URLs or read other local files. Probe with ffprobe first (in the same sandbox) and reject anything whose `format_name` isn't on your allowlist (for example `mov,mp4,m4a,3gp,3g2,mj2`, `matroska,webm`); never accept `hls`, `concat` or similar playlist formats. Then enforce limits (duration, resolution, stream count, allowed codecs). `-protocol_whitelist file` (an input option, placed before `-i`) blocks network protocols, but it still allows reading any local file, so it does not replace the format allowlist or the sandbox.
+4. **Bound the run**: a wall-clock timeout, `-threads` if sharing a host, `-nostdin` so it never waits for input, `-y` or `-n` decided explicitly (overwrite or fail), and run it in a sandbox or container without network for user uploads.
+5. **Check the exit code and stderr**, then ffprobe the output (duration within tolerance, expected streams). A zero exit code with a 0-second output is still a failure.
+6. Report progress with `-progress pipe:1 -nostats` and parse `out_time_us=`.
+
+## Never
+
+- Never put `-ss` and `-c copy` together when the user needs an exact cut, without telling them it will snap to a keyframe.
+- Never re-encode when `-c copy` does the job, and never stream-copy when the target needs a different codec.
+- Never build ffmpeg commands by concatenating strings from user input.
+- Never overwrite the source file; write to a new path and swap after verifying.
+
+## Stop and ask the user
+
+- Quality versus size trade-off when no target is given (CRF, resolution, bitrate cap).
+- Before deleting or replacing original media files.
+- When the source is DRM-protected or the user may not have rights to transcode it.
+
+## Report back
+
+The exact command(s), why copy or re-encode, the input and output ffprobe summary (codec, resolution, fps, duration, size), and any limit (keyframe snapping, hardware fallback) the user should know about.

package/skills/ffmpeg-media-processing/evals/triggers.json

@@ -0,0 +1,16 @@
+{
+  "should_trigger": [
+    "Convert this MOV from my iPhone into an MP4 that plays in every browser",
+    "Cut 00:02:10 to 00:02:40 out of the lecture recording without losing sync",
+    "Turn our uploaded videos into an HLS ladder with 1080p, 720p and 480p renditions",
+    "Our Node backend runs ffmpeg on user uploads with exec and a template string, make it safe",
+    "Use NVENC to speed up transcoding on the GPU box, the software encoder is too slow"
+  ],
+  "should_not_trigger": [
+    "Render my Remotion composition to MP4 on AWS Lambda",
+    "Animate a matrix multiplication step by step with Manim",
+    "Generate a voice-over track from a script using a text-to-speech API",
+    "Set up a CDN in front of our S3 bucket of images",
+    "Write a Dockerfile for our Python API with a small image"
+  ]
+}

package/skills/ffmpeg-media-processing/references/recipes.md

@@ -0,0 +1,112 @@
+# FFmpeg recipes
+
+Each recipe assumes the input was probed first. Adjust CRF, bitrates and sizes to the user's target. Check flags against `ffmpeg -h full` or ffmpeg.org/ffmpeg-all.html for the installed version.
+
+## Web-ready MP4 (H.264 + AAC)
+
+```bash
+ffmpeg -nostdin -i in.mov -c:v libx264 -preset medium -crf 23 -pix_fmt yuv420p \
+  -c:a aac -b:a 128k -movflags +faststart out.mp4
+```
+
+`+faststart` moves the index to the front so playback starts before the whole file downloads.
+
+## WebM (VP9 + Opus)
+
+```bash
+ffmpeg -nostdin -i in.mp4 -c:v libvpx-vp9 -crf 31 -b:v 0 -row-mt 1 -c:a libopus -b:a 96k out.webm
+```
+
+## Concatenate identical files (no re-encode)
+
+`list.txt` (paths relative to the list file, single-quoted):
+
+```text
+file 'part1.mp4'
+file 'part2.mp4'
+```
+
+```bash
+ffmpeg -nostdin -f concat -safe 0 -i list.txt -c copy joined.mp4
+```
+
+Only write `list.txt` from paths your code generated. `-safe 0` allows any path, so never use it with a list built from user input.
+
+## Concatenate different files (re-encode)
+
+```bash
+ffmpeg -nostdin -i a.mp4 -i b.mp4 -filter_complex \
+ "[0:v]scale=1280:720:force_original_aspect_ratio=decrease,pad=1280:720:(ow-iw)/2:(oh-ih)/2,setsar=1,fps=30[v0]; \
+  [1:v]scale=1280:720:force_original_aspect_ratio=decrease,pad=1280:720:(ow-iw)/2:(oh-ih)/2,setsar=1,fps=30[v1]; \
+  [v0][0:a][v1][1:a]concat=n=2:v=1:a=1[v][a]" \
+ -map "[v]" -map "[a]" -c:v libx264 -crf 20 -pix_fmt yuv420p -c:a aac out.mp4
+```
+
+Every input needs an audio stream for `a=1`; for a clip that has none, add a silent input of the same length, `-f lavfi -t <clip-seconds> -i anullsrc=r=48000:cl=stereo`, and use that input's audio in its place. The `-t` matters: `anullsrc` never ends on its own, and `-shortest` does not stop it inside `concat`.
+
+## Burn in subtitles with styling
+
+```bash
+ffmpeg -nostdin -i in.mp4 -vf "subtitles=subs.srt:force_style='FontName=Inter,FontSize=24,Outline=2'" \
+  -c:v libx264 -crf 20 -c:a copy out.mp4
+```
+
+Filter paths with `:` or `'` need escaping; copy the subtitle file to a simple generated name instead.
+
+## Add a soft subtitle track to MP4
+
+```bash
+ffmpeg -nostdin -i in.mp4 -i subs.srt -map 0 -map 1 -c copy -c:s mov_text -metadata:s:s:0 language=eng out.mp4
+```
+
+## Watermark / overlay
+
+```bash
+ffmpeg -nostdin -i in.mp4 -i logo.png -filter_complex "overlay=W-w-24:H-h-24" -c:v libx264 -crf 20 -c:a copy out.mp4
+```
+
+## GIF with a good palette
+
+```bash
+ffmpeg -nostdin -i in.mp4 -vf "fps=12,scale=480:-1:flags=lanczos,split[a][b];[a]palettegen[p];[b][p]paletteuse" out.gif
+```
+
+## HLS, single rendition (VOD)
+
+```bash
+ffmpeg -nostdin -i in.mp4 -c:v libx264 -crf 21 -g 48 -keyint_min 48 -sc_threshold 0 -c:a aac -b:a 128k \
+  -f hls -hls_time 6 -hls_playlist_type vod -hls_segment_filename "out/seg_%03d.ts" out/index.m3u8
+```
+
+A fixed GOP (`-g` = fps x 2 here for 24 fps and 2 s keyframes, `-sc_threshold 0`) keeps segment boundaries even. Use `-hls_segment_type fmp4` for fMP4 segments (needed for HEVC in HLS).
+
+## HLS ladder (three renditions, master playlist)
+
+```bash
+ffmpeg -nostdin -i in.mp4 -filter_complex \
+ "[0:v]split=3[v1][v2][v3];[v1]scale=w=1920:h=-2[v1o];[v2]scale=w=1280:h=-2[v2o];[v3]scale=w=854:h=-2[v3o]" \
+ -map "[v1o]" -c:v:0 libx264 -b:v:0 5000k -maxrate:v:0 5350k -bufsize:v:0 7500k \
+ -map "[v2o]" -c:v:1 libx264 -b:v:1 2800k -maxrate:v:1 2996k -bufsize:v:1 4200k \
+ -map "[v3o]" -c:v:2 libx264 -b:v:2 1400k -maxrate:v:2 1498k -bufsize:v:2 2100k \
+ -map 0:a:0 -map 0:a:0 -map 0:a:0 -c:a aac -b:a 128k -ac 2 \
+ -g 48 -keyint_min 48 -sc_threshold 0 -pix_fmt yuv420p \
+ -f hls -hls_time 6 -hls_playlist_type vod \
+ -hls_segment_filename "out/v%v/seg_%03d.ts" -master_pl_name master.m3u8 \
+ -var_stream_map "v:0,a:0 v:1,a:1 v:2,a:2" out/v%v/index.m3u8
+```
+
+`-map` always needs the input index (`0:a:0`, not `a:0`). `-g 48` assumes 24 fps (2 s GOP); set it to fps x 2 from the probe. The scale filters upscale small sources, so drop renditions taller than the input.
+
+Serve `.m3u8` as `application/vnd.apple.mpegurl` and `.ts` as `video/mp2t`, with CORS if the player is on another origin.
+
+## Extract audio and normalise loudness
+
+```bash
+ffmpeg -nostdin -i in.mp4 -vn -af loudnorm=I=-16:TP=-1.5:LRA=11 -c:a aac -b:a 160k voice.m4a
+```
+
+For best results run `loudnorm` twice: first with `print_format=json` to measure, then pass the measured values back.
+
+## Progress from code
+
+Add `-progress pipe:1 -nostats` and parse lines such as `out_time_us=12345678` and `progress=end` from stdout; divide by the probed duration for a percentage.

package/skills/fhir-integration/SKILL.md

@@ -0,0 +1,81 @@
+---
+name: fhir-integration
+description: HL7 FHIR R4 and R4B REST client and server work, covering resource modelling and references, search parameters with _include and chained queries, paging through Bundle next links, transaction and batch bundles with urn:uuid references, SMART on FHIR authorization (EHR and standalone launch, v2 scopes, PKCE, backend services), profile validation with $validate and the HL7 validator, and testing against public sandboxes. Use when calling or exposing a FHIR API, registering a SMART app with an EHR such as Epic or Oracle Health, writing FHIR search queries, posting transaction bundles, or debugging OperationOutcome errors.
+license: MIT
+compatibility: Any Agent Skills host. Live calls need network access to a FHIR server or sandbox. Examples use plain HTTP and JSON; the rules apply to any language or FHIR client library.
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: integrations
+  kete-loom/risk: network
+  kete-loom/owner: "Kete-org"
+---
+
+# FHIR integration
+
+Build a FHIR integration that reads and writes the right patient's data, survives paging and partial failure, and validates against the profiles the other side expects. This skill covers the FHIR REST API and SMART on FHIR. For HL7 v2 pipe-delimited messages use `hl7v2-integration`; for decision support cards use `clinical-decision-support`; for HIPAA safeguards around the data use `hipaa-compliance`.
+
+This is engineering guidance, not clinical or legal advice.
+
+## Ground rules
+
+1. **Pin the FHIR version.** Read `GET [base]/metadata` (the CapabilityStatement) and check `fhirVersion`: `4.0.1` is R4, `4.3.0` is R4B, `5.0.0` is R5. Never mix resource shapes across versions. Send `Accept: application/fhir+json` (optionally with `; fhirVersion=4.0`).
+2. **Trust the CapabilityStatement, not assumptions.** Which resources, interactions, search parameters, `_include`s and operations a server supports differs per server. Check `rest.resource[].searchParam` before relying on a parameter; unsupported parameters may be silently ignored, which returns too much data.
+3. **Patient identity is not a name match.** Find patients by a business identifier (`Patient?identifier=system|value`), never by name and birth date alone. If a match is ambiguous, stop and surface it to a human; never pick the first result.
+4. **References are typed and relative.** Write `"subject": {"reference": "Patient/123"}`. Resolve relative references against the server base. Treat `contained` resources as part of their parent only.
+5. **Follow paging to the end.** A search returns a `searchset` Bundle with at most `_count` entries; keep following `Bundle.link` where `relation = "next"` exactly as given (it is opaque) until there is none. `Bundle.total` is optional and may be absent or estimated.
+6. **Use the right bundle type.** `transaction` is all-or-nothing; `batch` runs entries independently and you must check every `entry.response.status`. Inside a transaction, link new resources with `fullUrl: "urn:uuid:<uuid>"` references, which the server rewrites to real IDs.
+7. **Writes are conditional and versioned.** Use conditional create (`If-None-Exist: identifier=system|value`) to avoid duplicates on retry, and `If-Match: W/"<versionId>"` on updates to avoid lost updates. A `412 Precondition Failed` means someone else changed it: re-read, re-apply, never force.
+8. **Errors are OperationOutcome.** On any 4xx/5xx read `OperationOutcome.issue[].severity`, `code` and `diagnostics`. Never log the request body or full resource when logging errors; it holds PHI. Log resource type, ID, status and issue codes.
+9. **Least-privilege SMART scopes.** Ask only for the scopes the feature needs, for example `patient/Observation.rs`, not `patient/*.cruds`. Keep tokens and refresh tokens server-side or in secure platform storage, never in `localStorage`.
+
+## Steps
+
+1. **Discover.** Fetch `[base]/metadata` and `[base]/.well-known/smart-configuration`. Record FHIR version, supported resources and search parameters, the `authorization_endpoint`, `token_endpoint`, supported scopes and `code_challenge_methods_supported`.
+2. **Pick the auth flow** with `references/smart-on-fhir.md`:
+   - App launched from inside the EHR: EHR launch (`launch` scope plus the `launch` parameter).
+   - App started by the user outside the EHR: standalone launch (`launch/patient`).
+   - Server-to-server job with no user: SMART Backend Services (`client_credentials` with a signed JWT `client_assertion`, `system/` scopes).
+3. **Identify the implementation guide.** In the US that is usually US Core; elsewhere a national base profile (for example AU Base, UK Core) or a project IG. Note the profile canonical URLs and must-support elements you must populate and handle.
+4. **Model the data.** Map each domain concept to a resource and profile. Use coded values with both `system` and `code` (LOINC for observations, SNOMED CT for clinical findings, RxNorm in the US for medications, UCUM for units). Never store free-text where the profile requires a code.
+5. **Query** with the patterns in `references/search-and-bundles.md`: one search with `_include` or `_revinclude` instead of N+1 reads, `_elements` or `_summary` to cut payloads, dates with prefixes (`ge`, `lt`).
+6. **Write** with conditional create or update, and transactions for sets of resources that must land together.
+7. **Validate** every resource you create against its profile before sending: `POST [base]/[type]/$validate` where supported, or the HL7 validator locally (`java -jar validator_cli.jar file.json -version 4.0.1 -ig <package>`). Treat `error` and `fatal` issues as blocking.
+8. **Test** against a sandbox before any real endpoint (see `references/search-and-bundles.md` for public servers). Use synthetic patients only (for example Synthea data); never paste real patient data into a public server.
+
+## Stop and ask the user
+
+- Before any write against a production EHR, or any test that uses real patient data.
+- When a patient search returns more than one candidate, or zero where one was expected.
+- When the server's version, IG or supported search parameters differ from what the code assumes.
+- Before requesting `user/*` or `system/*` wildcard scopes or `offline_access`.
+
+## Never
+
+- Never build search URLs by string concatenation of unescaped user input; URL-encode values, and escape a literal `,`, `$`, `|` or `\` inside a parameter value by prefixing it with `\`, per the FHIR search spec.
+- Never assume a single page of results is all results.
+- Never drop unknown extensions or modifier extensions on round-trip; a `modifierExtension` you don't understand can change meaning, so reject the resource instead of ignoring it.
+- Never treat `Observation.status = entered-in-error`, `cancelled` or `preliminary` results as final clinical data without handling the status.
+- Never put PHI in URLs that end up in access logs if a `POST [type]/_search` form is available.
+
+## Reviewing an existing integration
+
+Check each ground rule, then look for:
+
+- Paging stops after the first page, or the `next` link is rebuilt by hand.
+- Patient matched by name, or the first `Patient` search result used blindly.
+- Batch bundles where failed entries are never checked.
+- Updates without `If-Match`, retries without conditional create.
+- Search parameters the server does not list in its CapabilityStatement.
+- Tokens logged, stored in the browser, or scopes far broader than the feature.
+- Resources never validated against the required profile.
+
+## Report format
+
+When asked to review or design, finish with:
+
+```
+FHIR version / IG: <e.g. R4 4.0.1, US Core 6.1.0>
+Auth flow: <EHR launch | standalone | backend services> with scopes <list>
+Findings: <ranked list, file:line, rule broken, fix>
+Not verified: <server behaviours you could not test>
+```

package/skills/fhir-integration/evals/triggers.json

@@ -0,0 +1,16 @@
+{
+  "should_trigger": [
+    "Our SMART on FHIR app gets invalid_scope from the Epic sandbox, what scopes should we request?",
+    "Write a client that pulls all lab Observations for a patient from a FHIR R4 server, including every page",
+    "How do I post a Patient and its Encounter together in one FHIR transaction bundle so the reference resolves?",
+    "Validate our generated Condition resources against the US Core profile before we send them",
+    "Set up a backend services client_credentials flow with a signed JWT to export data from our EHR's FHIR API"
+  ],
+  "should_not_trigger": [
+    "Parse incoming ADT^A01 messages from the hospital's interface engine over MLLP",
+    "Build a CDS Hooks service that shows a warning card at order-sign",
+    "Do we need a BAA with our cloud vendor before storing patient records?",
+    "Review our patient portal code for PHI showing up in error logs",
+    "Design a REST API with pagination and versioning for our appointment booking service"
+  ]
+}

package/skills/fhir-integration/references/search-and-bundles.md

@@ -0,0 +1,73 @@
+# FHIR search, paging and bundles
+
+Source: FHIR R4 specification, http.html and search.html (hl7.org/fhir/R4). Check the target server's CapabilityStatement for what it really supports.
+
+## Search patterns
+
+| Need | Query |
+|---|---|
+| Patient by identifier | `GET Patient?identifier=http://hospital.example/mrn\|12345` |
+| Lab results since a date | `GET Observation?patient=Patient/123&category=laboratory&date=ge2024-01-01` |
+| Latest vitals | `GET Observation?patient=123&category=vital-signs&_sort=-date&_count=10` |
+| Specific code | `GET Observation?patient=123&code=http://loinc.org\|4548-4` |
+| Encounters plus their patient | `GET Encounter?date=ge2024-06-01&_include=Encounter:subject` |
+| Patient plus its conditions | `GET Patient?_id=123&_revinclude=Condition:subject` |
+| Chained search | `GET Observation?subject:Patient.identifier=http://hospital.example/mrn\|12345` |
+| Smaller payload | `_summary=true`, or `_elements=id,code,valueQuantity` |
+| Long or PHI-bearing query | `POST Observation/_search` with `application/x-www-form-urlencoded` body |
+
+Modifiers: `:exact`, `:contains` (strings), `:missing=true`, `:not`, `:text` (tokens). Date prefixes: `eq ne gt lt ge le sa eb ap`.
+
+`_include`d resources come back with `entry.search.mode = "include"`; only `"match"` entries are search results.
+
+## Paging
+
+```
+url = first search URL
+loop:
+  bundle = GET url
+  for entry in bundle.entry where entry.search.mode == "match": handle(entry.resource)
+  next = bundle.link.find(l => l.relation == "next")
+  if not next: break
+  url = next.url   # opaque; never rebuild it
+```
+
+Some servers expire paging cursors; handle a 4xx on a `next` link by restarting the search, not by skipping.
+
+## Transaction bundle
+
+```json
+{
+  "resourceType": "Bundle",
+  "type": "transaction",
+  "entry": [
+    {
+      "fullUrl": "urn:uuid:3f1c...",
+      "resource": { "resourceType": "Patient", "identifier": [{ "system": "http://hospital.example/mrn", "value": "12345" }] },
+      "request": { "method": "POST", "url": "Patient", "ifNoneExist": "identifier=http://hospital.example/mrn|12345" }
+    },
+    {
+      "resource": { "resourceType": "Observation", "status": "final", "code": { "coding": [{ "system": "http://loinc.org", "code": "4548-4" }] }, "subject": { "reference": "urn:uuid:3f1c..." } },
+      "request": { "method": "POST", "url": "Observation" }
+    }
+  ]
+}
+```
+
+POST it to `[base]` (not to a resource type). Success returns a `transaction-response` Bundle with one `entry.response` per entry, in order, each with `status` and `location`. Any failure rolls back everything and returns an OperationOutcome.
+
+Use `batch` only when entries are truly independent, and check each `entry.response.status`.
+
+## Other interactions
+
+- `GET Patient/123/_history/2`: a specific version.
+- `GET Patient/123/$everything`: everything for a patient, where supported (paged).
+- `GET Observation?_lastUpdated=gt2024-06-01T00:00:00Z`: incremental sync.
+- Bulk Data (`$export`, async with `Prefer: respond-async`, NDJSON output): for population-scale extracts; use backend services auth.
+
+## Public test servers (synthetic data only)
+
+- HAPI FHIR public server: `https://hapi.fhir.org/baseR4` (shared, data is public and wiped occasionally).
+- SMART App Launcher: `https://launch.smarthealthit.org` (simulates EHR and standalone launch).
+- Vendor sandboxes: Epic on FHIR (fhir.epic.com) and Oracle Health (Cerner) code console; each requires registering an app.
+- Run your own: the `hapiproject/hapi` Docker image for a local server you can reset.

package/skills/fhir-integration/references/smart-on-fhir.md

@@ -0,0 +1,50 @@
+# SMART on FHIR authorization
+
+Source: SMART App Launch IG (STU 2.x, hl7.org/fhir/smart-app-launch). Check the EHR vendor's own developer docs for registration steps and which scopes they actually grant.
+
+## Discovery
+
+`GET [base]/.well-known/smart-configuration` returns JSON with `authorization_endpoint`, `token_endpoint`, `scopes_supported`, `capabilities` (for example `launch-ehr`, `launch-standalone`, `client-public`, `client-confidential-asymmetric`, `context-ehr-patient`, `permission-v2`) and `code_challenge_methods_supported`.
+
+## Scopes (v2 syntax)
+
+`<context>/<ResourceType>.<letters>` where context is `patient`, `user` or `system`, and letters are a subset of `c r u d s` in that order.
+
+| Scope | Meaning |
+|---|---|
+| `patient/Observation.rs` | read and search Observations for the patient in context |
+| `patient/Observation.rs?category=http://terminology.hl7.org/CodeSystem/observation-category\|laboratory` | same, limited to lab results |
+| `user/Patient.rs` | read and search any Patient the user may see |
+| `system/*.rs` | backend service, read everything granted to the client |
+| `launch` | EHR launch; pair with the `launch` URL parameter |
+| `launch/patient` | standalone launch; ask the EHR to select a patient |
+| `openid fhirUser` | ID token with a `fhirUser` claim (the user's Practitioner/Patient URL) |
+| `offline_access` / `online_access` | refresh token, long-lived or only while the user is online |
+
+v1 servers use `.read`, `.write`, `.*`. v1 `.read` maps to v2 `.rs`, `.write` to `.cud`. Request what the server advertises (`permission-v1` / `permission-v2`). The granted scopes in the token response can be narrower than requested: always read `scope` from the response and degrade the feature, rather than assuming.
+
+## EHR launch
+
+1. EHR opens your launch URL with `iss` (the FHIR base) and `launch` (an opaque handle).
+2. Check `iss` against an allowlist of FHIR bases you registered with. Never fetch configuration from an arbitrary `iss`.
+3. Redirect to `authorization_endpoint` with `response_type=code`, `client_id`, `redirect_uri`, `scope` (including `launch`), `state` (random, checked on return), `aud` (= the FHIR base), `launch`, `code_challenge` and `code_challenge_method=S256`.
+4. Exchange the code at `token_endpoint` with `code_verifier`. The response carries `access_token`, `expires_in`, `scope`, and context such as `patient`, `encounter`, `id_token`, `refresh_token`.
+5. Use only the `patient` in the token response as the patient in context.
+
+## Standalone launch
+
+Same as EHR launch without `iss`/`launch` from the EHR: you know the base in advance and request `launch/patient`.
+
+## Backend services (no user)
+
+1. Register a public key (JWKS URL or JWK) with the server.
+2. Build a JWT signed with `RS384` or `ES384`: `iss` and `sub` = client_id, `aud` = token endpoint, `exp` at most 5 minutes ahead, unique `jti`.
+3. `POST token_endpoint` with `grant_type=client_credentials`, `scope=system/...`, `client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer`, `client_assertion=<jwt>`.
+4. Cache the token until shortly before `expires_in`.
+
+## Common failures
+
+- `invalid_scope`: the scope isn't registered for the client, or v1/v2 syntax mismatch.
+- `invalid_client` on backend services: wrong `aud`, clock skew on `exp`, wrong algorithm, or a key not yet registered.
+- 401 on FHIR calls: token expired, or `aud` didn't match the FHIR base.
+- 403 on a resource: scope granted is narrower than requested, or the user lacks access in the EHR.

package/skills/flask-patterns/SKILL.md

@@ -0,0 +1,132 @@
+---
+name: flask-patterns
+description: Flask application structure with a create_app factory, blueprints per feature, config loaded from objects and environment variables, extensions such as Flask-SQLAlchemy and Flask-Migrate initialised with init_app, application and request context pitfalls with current_app and g, security hardening, and pytest tests through the test client. Use when starting or restructuring a Flask app, adding a blueprint or extension, debugging "working outside of application context" errors, or testing Flask views.
+license: MIT
+compatibility: Any Agent Skills host. Needs Python and the project's Flask app. Guidance targets Flask 2.x and 3.x with Flask-SQLAlchemy 3.
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: coding
+  kete-loom/risk: runs-commands
+  kete-loom/requires: "python"
+  kete-loom/owner: "Kete-org"
+---
+
+# Flask patterns
+
+Keep a Flask app importable without side effects, configurable per environment, and testable with a fresh app per test.
+
+## 0. Before you change anything
+
+1. Find the app: a `create_app()` factory or a module-level `app = Flask(__name__)`. Check Flask and extension versions in `pyproject.toml` or `requirements*.txt`.
+2. Find how it runs (`flask --app <module> run`, gunicorn target, `FLASK_APP`) and how tests run. Run the tests once; if they already fail, **stop and tell the user**.
+3. If the app is a single module-level `app`, ask the user before converting it to a factory; it touches every import of `app`.
+
+## 1. Application factory
+
+```python
+# myapp/__init__.py
+from flask import Flask
+from .extensions import db, migrate
+
+def create_app(config_object="myapp.config.Config", test_config=None):
+    app = Flask(__name__, instance_relative_config=True)
+    app.config.from_object(config_object)
+    app.config.from_prefixed_env()          # FLASK_SECRET_KEY, FLASK_SQLALCHEMY_DATABASE_URI, ...
+    if test_config:
+        app.config.update(test_config)
+
+    db.init_app(app)
+    migrate.init_app(app, db)
+
+    from .orders import bp as orders_bp
+    app.register_blueprint(orders_bp, url_prefix="/orders")
+    return app
+```
+
+- Extensions are created unbound in `extensions.py` (`db = SQLAlchemy()`) and bound with `init_app(app)` in the factory. This avoids circular imports and lets tests build many apps.
+- Import blueprints inside the factory (or in a module that doesn't import the app) to avoid import cycles.
+- No work at import time: no database connections, no reading secrets into module globals, no `app.run()` outside `if __name__ == "__main__":`.
+
+## 2. Blueprints
+
+- One blueprint per feature (`auth`, `orders`, `admin`), each in its own package with `routes.py`, templates in a per-blueprint subfolder of the templates folder.
+- Use `url_for("orders.detail", order_id=o.id)` (blueprint-qualified endpoint names), never hard-coded paths.
+- Protect a whole blueprint with `@bp.before_request` that checks login or role, then add per-view checks for object ownership.
+- Register error handlers per blueprint with `@bp.errorhandler` or app-wide with `@app.errorhandler`; return JSON for API blueprints and HTML for page blueprints, consistently.
+
+## 3. Config
+
+- Base `Config` class with safe defaults, subclasses `DevConfig`, `TestConfig`, `ProdConfig` if the project uses them; or one class plus environment variables.
+- `SECRET_KEY` and database URLs come from the environment or the `instance/` folder (which is not committed). Fail at startup in production if `SECRET_KEY` is missing.
+- Read config at request time through `current_app.config["KEY"]`, not by importing a module constant, so tests can override it.
+- `DEBUG`/`app.debug` must be off in production; the Werkzeug debugger allows arbitrary code execution.
+
+## 4. Flask-SQLAlchemy and Flask-Migrate
+
+- Use the session the extension scopes to the app context: `db.session`. It is removed at the end of each request; don't create your own `Session()` per request.
+- SQLAlchemy 2 style queries: `db.session.execute(db.select(Order).filter_by(owner_id=uid)).scalars()`, `db.get_or_404(Order, id)`, `db.paginate(...)`. Follow the existing style if the project still uses `Model.query`.
+- Avoid N+1 queries with `selectinload`/`joinedload` in `options(...)` when a template walks a relationship.
+- Commit once per unit of work; on exception call `db.session.rollback()` before re-raising or returning an error.
+- Migrations: `flask db migrate -m "add order status"`, read the generated script (autogenerate misses renames and some type changes), then `flask db upgrade`. Run `flask db downgrade` and `upgrade` again locally to prove reversibility.
+- **Stop and ask the user** before a migration that drops columns or tables or rewrites a large table. Never run `flask db upgrade` against a shared or production database yourself.
+
+## 5. Contexts: current_app, g, request, session
+
+| Symptom | Cause | Fix |
+|---|---|---|
+| `RuntimeError: Working outside of application context` | Using `current_app`, `db.session` or `g` in a script, CLI, thread or test with no app pushed | `with app.app_context():` around the work, or use a `@app.cli.command()` (which pushes one) |
+| `Working outside of request context` | Touching `request` or `session` outside a request | Pass values in as arguments; in tests use `app.test_request_context()` |
+| Data shared between users | Storing per-request state in a module global | Store it on `g` (lives for one app context) |
+| Background thread loses context | Contexts are per thread | Pass plain data and push `app.app_context()` in the thread; better, use a task queue |
+
+- Never pass `request`, `g` or `current_app` proxies to a thread or task. Use `current_app._get_current_object()` only when you must hand the real app object over.
+
+## 6. Security
+
+- Forms: Flask-WTF's `CSRFProtect` (create `csrf = CSRFProtect()` in `extensions.py`, call `csrf.init_app(app)` in the factory) for any cookie-authenticated POST. Exempt only token-authenticated API endpoints, and say why.
+- Cookies in production: `SESSION_COOKIE_SECURE=True`, `SESSION_COOKIE_HTTPONLY=True` (default), `SESSION_COOKIE_SAMESITE="Lax"`. The default session is signed, not encrypted: never put secrets in it.
+- Templates autoescape `.html` files; never use `Markup(...)` or `|safe` on user input, and never `render_template_string` with user-controlled template text.
+- Uploads: `secure_filename`, `MAX_CONTENT_LENGTH`, an allow-list of extensions, and save outside the static folder.
+- Redirects: validate `next` parameters against your own host before redirecting.
+- SQL: use the ORM or `text()` with bound parameters, never f-strings.
+- Behind a proxy, wrap with `werkzeug.middleware.proxy_fix.ProxyFix` set to the real number of proxies, not more.
+
+## 7. Testing
+
+```python
+# tests/conftest.py
+import pytest
+from myapp import create_app
+from myapp.extensions import db
+
+@pytest.fixture
+def app():
+    app = create_app(test_config={"TESTING": True,
+                                  "SQLALCHEMY_DATABASE_URI": "sqlite:///:memory:",
+                                  "WTF_CSRF_ENABLED": False})
+    with app.app_context():
+        db.create_all()
+    yield app                   # outside the context, so tests catch missing-context bugs
+    with app.app_context():
+        db.drop_all()
+
+@pytest.fixture
+def client(app):
+    return app.test_client()
+```
+
+- A fresh app per test via the factory; never import a shared global app into tests.
+- Use `client.get/post(...)`, `follow_redirects=True` where the flow redirects, and `with client.session_transaction() as s:` to set session state.
+- Test CLI commands with `app.test_cli_runner()`.
+- If production uses PostgreSQL, run at least the query-heavy tests against PostgreSQL; SQLite hides type and constraint differences.
+- For each view: happy path, invalid form, unauthenticated, another user's object.
+
+## Rules
+
+- Never leave `debug=True` or a hard-coded `SECRET_KEY` in committed code.
+- Never disable CSRF outside test config.
+- Never add global mutable state for per-request data.
+
+## Report back
+
+End with: files changed, blueprints and routes added, extensions or config keys added, migrations generated (with what you checked in the script), the test command and result, and anything left untested.

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

@@ -0,0 +1,16 @@
+{
+  "should_trigger": [
+    "Convert my single-file Flask app into an application factory with blueprints",
+    "I get RuntimeError: Working outside of application context in my Flask CLI script",
+    "Add Flask-SQLAlchemy and Flask-Migrate to this Flask project",
+    "Write pytest tests for my Flask login view using the test client",
+    "How do I load Flask config from environment variables per environment?"
+  ],
+  "should_not_trigger": [
+    "Add a Django admin page for the orders model",
+    "Create FastAPI dependencies for the database session",
+    "Review my Django change for unsafe raw SQL",
+    "Write a Dockerfile to deploy my Python web app",
+    "Fix the pip dependency conflict that stops my Python package from installing"
+  ]
+}