@pikaa-ai/pikaa 0.3.22 → 0.3.24

package/skills/generate-image/SKILL.md

@@ -1,304 +0,0 @@
----
-name: generate-image
-description: Generate or edit images with AI models through the OpenRouter Image API (Gemini, Seedream, Recraft, GPT-Image, Riverflow). Use for photos, illustrations, artwork, concept art, visual assets, logos, and image editing or compositing from reference images. For flowcharts, circuits, pathways, and other technical diagrams, use the scientific-schematics skill instead.
-license: MIT
-compatibility: Requires Python 3.9+ and network access to openrouter.ai. The bundled script uses only the standard library. Image generation requires the OPENROUTER_API_KEY credential and bills per request; listing models, inspecting a model, and --dry-run do not. Targets the OpenRouter Image API (POST /api/v1/images) as verified on 2026-07-31.
-allowed-tools: Read Write Edit Bash
-metadata:
-  version: "3.0"
-  skill-author: K-Dense Inc.
-  last-reviewed: "2026-07-31"
-  openclaw:
-    primaryEnv: OPENROUTER_API_KEY
-    envVars:
-      - name: OPENROUTER_API_KEY
-        required: true
-        description: OpenRouter API key used for image generation.
----
-
-# Generate Image
-
-Generate and edit images through OpenRouter's Image API, which reaches Gemini, Seedream, Recraft,
-GPT-Image, Riverflow, and roughly thirty other models behind one request shape.
-
-## When to use
-
-**Use this skill for:** photos and photorealistic images, illustrations and artwork, concept art,
-presentation and poster visuals, logos and vector marks, image editing, and compositing from
-reference images.
-
-**Use `scientific-schematics` instead for:** flowcharts, circuit diagrams, biological pathways,
-system architecture diagrams, CONSORT diagrams, and other technical schematics.
-
-## API key
-
-Generation requires an OpenRouter key. The script resolves it in this order:
-
-1. `--api-key`
-2. the `OPENROUTER_API_KEY` environment variable
-3. `OPENROUTER_API_KEY=` in a `.env` file, searching the working directory upward, then the
-   script's own directory
-
-If none is present the script exits with setup instructions. Keys: https://openrouter.ai/keys
-
-`--list-models`, `--model-info`, and `--dry-run` need no key.
-
-## Quick start
-
-```bash
-# Generate
-python scripts/generate_image.py "A beautiful sunset over mountains"
-
-# Edit an existing image
-python scripts/generate_image.py "Make the sky purple" -i photo.jpg -o edited.png
-```
-
-Paths are relative to this skill's directory. Output defaults to `generated_image.<ext>`, where the
-extension follows the media type the model returned. The per-request cost is printed after the run.
-
-**Then look at the image.** Read the file back and check it before using it anywhere: composition,
-aspect ratio, and any text are all things models get wrong silently.
-
-## Choosing a model
-
-Default: `google/gemini-3.1-flash-image`.
-
-| Need | Model |
-| --- | --- |
-| General quality, prompt adherence | `google/gemini-3.1-flash-image` |
-| Highest Gemini tier | `google/gemini-3-pro-image` |
-| Cheap iteration | `google/gemini-3.1-flash-lite-image` (1K only), `openai/gpt-image-1-mini` |
-| Photoreal control, reproducible seeds | `bytedance-seed/seedream-4.5` |
-| Several images per request | `bytedance-seed/seedream-4.5`, `openai/gpt-image-2` (up to 10) |
-| Vector / SVG output | `recraft/recraft-v4.1-vector` |
-| Transparent background | `openai/gpt-image-1` with `--background transparent` |
-| Legible text inside the image | `recraft/recraft-v4.1`, `sourceful/riverflow-v2.5-pro` — see the caveat below |
-
-`references/models.md` carries the full catalogue with per-model parameters, allowed values, and
-prices. The live listing is authoritative and free:
-
-```bash
-python scripts/generate_image.py --list-models            # every model and its allowed values
-python scripts/generate_image.py --list-models gemini     # filtered by substring
-python scripts/generate_image.py --model-info openai/gpt-image-1   # one model, plus pricing
-```
-
-## Parameter support varies by model
-
-This is the main thing to get right. Models advertise different parameter sets **and different
-allowed values**, and sending something a model does not support is rejected, not ignored.
-
-The script checks the request against the live catalogue before spending anything, so a bad
-parameter fails locally in under a second with the legal values printed:
-
-```console
-$ python scripts/generate_image.py "abstract pattern" -m openai/gpt-image-2 --background transparent
-Error: Request rejected before billing (1 problem):
-  - background=transparent is not allowed; this model accepts: auto, opaque
-```
-
-Rough guide — but let the check be the authority, since the catalogue moves:
-
-- `--resolution` — Gemini, Seedream, Riverflow, Krea, Grok. The tiers differ: `512` only on Gemini
-  3.1 Flash, `4K` on Gemini 3 Pro / Seedream / Riverflow, and **`1K` only** on
-  `gemini-3.1-flash-lite-image` and the Krea models.
-- `--output-format` — Riverflow 2.5 only (`png`, `jpeg`, `webp`; the `fast` variant takes `jpeg`
-  alone). Gemini, OpenAI, Seedream, and Recraft all choose their own container.
-- `--quality`, `--background`, `--output-compression` — the OpenAI family, plus `--background` on
-  Riverflow 2.5. **`--background transparent` is not available on `gpt-image-2` or
-  `gpt-5.4-image-2`** — use `gpt-image-1`, `gpt-image-1-mini`, `gpt-5-image`, or `gpt-5-image-mini`.
-- `--seed` — Seedream and Krea. Not Gemini, not OpenAI.
-- `--aspect-ratio` — nearly all models, but the enum differs sharply: `gpt-image-1` accepts only
-  `1:1`, `3:2`, `2:3`, `auto`, and `gpt-5-image*` does not accept it at all.
-- `--n` — capped per model: 1 for Gemini, Riverflow, MAI and Grok, 6 for Recraft, 10 for Seedream
-  and OpenAI. The Krea models reject it outright.
-
-Pass `--dry-run` to validate and print the exact request body without generating or billing.
-`--no-preflight` skips the check when you want the API itself to arbitrate.
-
-## Writing the prompt
-
-Prompt quality decides output quality more than model choice does. Name, in one sentence each:
-
-1. **Subject** — what is in frame, and how much of it. "A single pipette tip above a 96-well plate."
-2. **Medium and style** — photograph, watercolour, 3D render, flat vector, scientific illustration.
-3. **Lighting and palette** — "soft diffuse lighting, cool blue and white palette."
-4. **Composition** — "wide shot, subject left of centre, empty space on the right for a title."
-5. **What to avoid** — "no text, no labels, no watermark."
-
-Asking for empty space where a caption or title will go is the single most useful compositional
-instruction for posters and slides.
-
-Iterate cheaply: draft on `gemini-3.1-flash-lite-image`, then regenerate the wording you settled on
-with the model you actually want. To refine rather than restart, feed the last output back as a
-reference (`-i out.png`) and describe only the change.
-
-## Editing and reference images
-
-`-i/--input` is repeatable and accepts local paths, HTTP(S) URLs, or data URLs. Local files are
-base64-encoded and sent as `input_references`.
-
-```bash
-# Single-image edit
-python scripts/generate_image.py "Add sunglasses to the person" -i portrait.png
-
-# Composite several references
-python scripts/generate_image.py "Blend these two styles" -i style_a.png -i style_b.jpg -o blend.png
-
-# Reference an image already on the web
-python scripts/generate_image.py "Restyle as a watercolor" -i https://example.com/photo.jpg
-```
-
-Reference limits differ: 16 for OpenAI, 14 for Gemini and Seedream, 10 for `riverflow-v2*-pro`,
-3 for `gemini-2.5-flash-image` and Grok, 1 for Recraft, MAI, and Krea. Accepted local formats: PNG,
-JPEG, GIF, WebP. Riverflow v2 bills $0.20 per reference image on top of the output.
-
-## Worked examples
-
-The `-o` paths are destinations the script creates, not files bundled with the skill.
-
-```bash
-# Wide hero image for a poster, with space reserved for the title
-python scripts/generate_image.py \
-  "Laboratory with modern equipment, photorealistic, well-lit, wide shot, \
-   equipment on the left, empty wall on the right, no text" \
-  --aspect-ratio 21:9 --resolution 2K -o poster/hero.png
-
-# Conceptual illustration for a manuscript — illustrative, never presented as data
-python scripts/generate_image.py \
-  "Stylised illustration of immune cells surrounding a tumour cell, scientific illustration, \
-   cool palette, no text" \
-  --resolution 2K -o figures/immunotherapy_concept.png
-
-# Vector logo
-python scripts/generate_image.py \
-  "Minimal geometric fox logo, two colors" \
-  -m recraft/recraft-v4.1-vector -o assets/logo.svg
-
-# Slide background with a transparent alpha channel
-python scripts/generate_image.py \
-  "Abstract molecular pattern, subtle, blue and white, no text" \
-  -m openai/gpt-image-1 --background transparent -o slides/bg.png
-
-# Four variations in one request
-python scripts/generate_image.py \
-  "Stylized neuron network illustration" \
-  -m bytedance-seed/seedream-4.5 --n 4 -o variations.png
-# -> variations_1.png ... variations_4.png
-
-# Reproducible output
-python scripts/generate_image.py "A cat astronaut" \
-  -m bytedance-seed/seedream-4.5 --seed 42
-
-# Check a request costs nothing to get wrong
-python scripts/generate_image.py "A cat astronaut" --resolution 4K --dry-run
-```
-
-## Script parameters
-
-| Flag | Purpose |
-| --- | --- |
-| `prompt` | Image description, or the edit to apply (required unless `--list-models` / `--model-info`) |
-| `-m`, `--model` | Model slug (default `google/gemini-3.1-flash-image`) |
-| `-o`, `--output` | Output path; extension defaults to the returned media type |
-| `-i`, `--input` | Reference image — path, URL, or data URL. Repeatable |
-| `--n` | Images per request, model-capped |
-| `--aspect-ratio` | `1:1`, `16:9`, `9:16`, `4:3`, `3:2`, `21:9`, … — enum differs per model |
-| `--resolution` | `512`, `1K`, `2K`, `4K` — tiers differ per model |
-| `--quality` | `auto`, `low`, `medium`, `high` (OpenAI) |
-| `--output-format` | `png`, `jpeg`, `webp` (Riverflow 2.5) |
-| `--background` | `auto`, `transparent`, `opaque` |
-| `--output-compression` | 0–100, OpenAI models |
-| `--seed` | Deterministic output where supported |
-| `--api-key` | Overrides the environment and `.env` |
-| `--timeout` | Request timeout, seconds (default 300) |
-| `--retries` | Retries for rate limits and 5xx responses (default 2) |
-| `--no-preflight` | Skip the free capability check before the billed request |
-| `--dry-run` | Validate and print the request, then exit without generating |
-| `--list-models` | Print the catalogue with allowed values, optionally filtered, then exit |
-| `--model-info` | Print one model's allowed values and pricing, then exit |
-
-There is no `--size`: no model in the catalogue accepts a `size` parameter. Shape output with
-`--aspect-ratio` and `--resolution`.
-
-## API shape
-
-For direct requests without the script:
-
-```bash
-curl -s https://openrouter.ai/api/v1/images \
-  -H "Authorization: Bearer $OPENROUTER_API_KEY" \
-  -H "Content-Type: application/json" \
-  -d '{
-    "model": "google/gemini-3.1-flash-image",
-    "prompt": "A red bicycle against a white wall",
-    "aspect_ratio": "16:9"
-  }'
-```
-
-Response:
-
-```json
-{
-  "created": 1748372400,
-  "data": [{ "b64_json": "<base64>", "media_type": "image/png" }],
-  "usage": {
-    "prompt_tokens": 4,
-    "completion_tokens": 1120,
-    "total_tokens": 1124,
-    "cost": 0.0672,
-    "completion_tokens_details": { "image_tokens": 1120 }
-  }
-}
-```
-
-`b64_json` is raw base64, **not** a data URL. `media_type` reflects the real format, so honour it
-when naming files — vector models return `image/svg+xml`, and `gemini-3.1-flash-lite-image` returns
-JPEG rather than PNG.
-
-Streaming (`"stream": true`) emits `image_generation.partial_image`, `image_generation.completed`,
-and `error` events, terminating with `data: [DONE]`. Only the OpenAI models support it, and the
-bundled script does not use it.
-
-Billing is all-or-nothing: a generation is either completed and billed in full, or it fails and is
-not billed — so a rejected parameter costs nothing but time. Streaming preview frames are not
-charged separately. On a bring-your-own-key account `usage.cost` reads `0` and the real amount is
-in `cost_details.upstream_inference_cost`; the script reports that figure rather than claiming the
-run was free.
-
-## Cost
-
-Per-image models are predictable: Seedream $0.04, Recraft v4.1 $0.035 (vector $0.08, pro $0.21),
-Riverflow 2.5 fast $0.019 and pro $0.13–0.17, Grok $0.05–0.07.
-
-Gemini, OpenAI, and MAI bill per output token, which scales with resolution — a 4K image costs
-roughly sixteen times a 1K one. Measured: one 1K `gemini-3.1-flash-lite-image` render is 1120
-output tokens, $0.034. At the same size `gemini-3.1-flash-image` is double that and
-`gemini-3-pro-image` four times. Draft at low resolution on a cheap model; pay for size once.
-
-## Notes and caveats
-
-- **Models cannot be trusted with text.** Words inside a generated image come back misspelled,
-  garbled, or invented. Ask for "no text" and overlay real type in LaTeX, PowerPoint, or HTML — or
-  use `scientific-schematics` when labels are the point.
-- **A generated image is an illustration, never evidence.** It shows nothing that was measured.
-  Never present one as microscopy, imaging, gel, or instrument output, never let it stand in for a
-  figure that reports results, and label it as an illustration in captions. Nature and Science both
-  require disclosure of generative-AI imagery, and several journals prohibit it outside
-  clearly-marked concept art — check the target venue before submitting.
-- Generation is a paid API call. Prefer a cheap model and low resolution while iterating on wording.
-- Generation takes roughly 5–60 seconds depending on model and resolution.
-- Reference images are uploaded to OpenRouter. Do not send unpublished or sensitive data, patient
-  images, or anything under embargo.
-- Never hardcode the API key. Keep it in the environment or an ignored `.env`.
-- Prompt specifically when editing: "change the sky to sunset colours" beats "edit the sky".
-- A refusal arrives as an HTTP 400 or 403 mentioning content policy, not as a bad image. Rephrase —
-  clinical and anatomical subjects trip moderation more often than the request warrants.
-- Rate limits and 5xx responses are retried automatically; a 4xx is final, because the request
-  itself is what needs changing.
-
-## Related skills
-
-- `scientific-schematics` — technical diagrams, flowcharts, circuits, pathways
-- `scientific-slides` — presentations that embed generated visuals
-- `latex-posters` — posters that embed hero images

package/skills/geniml/SKILL.md

@@ -1,310 +0,0 @@
----
-name: geniml
-description: "Use Geniml for audited local genomic-interval workflows: validate BED and universe contracts, plan Region2Vec or scEmbed runs, inspect model/tokenizer compatibility, and assess consensus universes."
-license: MIT
-compatibility: Requires Python 3.10+ and uv. Guidance targets geniml 0.8.4 with gtars 0.9.2; ML workflows need the pinned ml extra and compatible native wheels. Bundled planners and inspectors are dependency-free, local-only, and make no network requests.
-allowed-tools: Read Write Edit Bash Glob
-metadata:
-  version: "1.1"
-  skill-author: "K-Dense Inc."
-  upstream-version: "0.8.4"
-  last-reviewed: "2026-07-23"
----
-
-# Geniml
-
-Use Geniml for machine learning and statistical workflows over genomic interval
-sets. Treat coordinates, assemblies, token vocabularies, model artifacts, and
-sample grouping as explicit contracts. The bundled scripts validate or plan;
-they do not import Geniml, contact services, deserialize models, or execute
-training.
-
-`Bash` is declared only for explicit, user-approved `uv`, Python, Geniml,
-Gtars, Git, and native CLI commands shown in this guide; bundled Python helpers
-do not spawn subprocesses. Example paths under `data/`, `refs/`, `work/`, and
-`models/` are user-provided project placeholders, not missing bundled files.
-
-## Verified release snapshot
-
-- Latest stable PyPI release on 2026-07-23: `geniml==0.8.4` (2026-01-14).
-- PyPI does not declare `Requires-Python`; its classifiers list Python
-  3.10-3.14. Prefer Python 3.11 or 3.12 where all native/ML wheels resolve.
-- `geniml==0.8.4` accepts `gtars>=0.2.5`; the verified base smoke used current
-  `gtars==0.9.2` (2026-06-17, Python >=3.10).
-- Extras are `ml` and `test`. The base install omits Torch, Gensim, Scanpy,
-  Hugging Face Hub, pyBigWig, and HMM dependencies.
-- Upstream documentation contains stale examples. Release source and installed
-  `--help` output take precedence where they conflict.
-
-## Install reproducibly
-
-Use a project environment and commit its generated lockfile:
-
-```bash
-uv venv --python 3.12
-uv pip install "geniml==0.8.4" "gtars==0.9.2"
-```
-
-For Region2Vec, scEmbed, evaluation, or universe methods needing ML libraries:
-
-```bash
-uv pip install "geniml[ml]==0.8.4" "gtars==0.9.2"
-```
-
-For a durable project, prefer:
-
-```bash
-uv add "geniml[ml]==0.8.4" "gtars==0.9.2"
-uv lock
-```
-
-Do not install an unpinned Git branch. Record Python, OS/architecture, the
-resolved lockfile, and the PyPI artifact digest. Geniml itself is BSD-2-Clause;
-the `MIT` frontmatter value licenses this skill's content.
-
-## Start with the safety gate
-
-Before importing Geniml or running an external binary:
-
-1. Work only with explicit local regular files. Reject URLs, FIFOs, devices,
-   and symlinks unless the user deliberately changes that policy.
-2. Validate BED structure and the declared assembly against a trusted local
-   chromosome-sizes file.
-3. Bound file count, bytes, rows, workers, epochs, and output size.
-4. Separate train/validation/test by patient, donor, biological replicate, or
-   other independent unit—not by BED row or cell alone.
-5. Inventory and checksum the universe, tokenizer, model, config, inputs,
-   metadata manifest, and native binaries.
-6. Obtain explicit approval before any BEDbase or Hugging Face download. Never
-   infer approval from a model ID or BEDbase identifier.
-7. Keep logs aggregate and bounded. BED filenames, sample IDs, phenotypes,
-   labels, barcodes, and genomic intervals may be sensitive.
-
-## Coordinate and assembly contract
-
-BED intervals are normally **0-based, half-open** `[start, end)`: start is
-included, end is excluded, and length is `end - start`. Do not mix them with
-1-based closed coordinates from VCF/GFF or user-facing genome browsers.
-
-For every corpus and artifact, record:
-
-- assembly and patch/accession where possible (for example GRCh38 versus
-  GRCh38.p14), plus the chromosome-sizes checksum;
-- contig naming convention (`chr1` versus `1`), alt/random/decoy policy, and
-  mitochondrial naming;
-- coordinate convention, sorting order, duplicate/overlap policy, and whether
-  BED strand is meaningful;
-- liftover tool, chain digest, source/target assemblies, unmapped fraction, and
-  post-liftover validation.
-
-Reject negative coordinates, `end <= start`, integer overflow, unknown
-contigs, ends beyond contig length, malformed columns, mixed assemblies, and
-silent contig renaming. Sorting and normalization never repair an assembly
-mismatch. BED3 has no strand; when column 6 is present, preserve `+`, `-`, or
-`.` unless the assay contract says otherwise.
-
-Run a bounded validation and normalization **plan** before analysis:
-
-```bash
-python skills/geniml/scripts/bed_validator.py \
-  --input data/peaks.bed \
-  --assembly GRCh38 \
-  --chrom-sizes refs/GRCh38.chrom.sizes
-```
-
-The validator reports proposed actions but never rewrites the BED file.
-
-## Current API map
-
-### Region and tokenizer I/O
-
-Prefer Gtars for new interval/tokenizer code:
-
-```python
-from gtars.models import Region, RegionSet
-from gtars.tokenizers import Tokenizer
-
-regions = RegionSet("data/peaks.bed")
-tokenizer = Tokenizer.from_bed("refs/universe.bed")
-encoded = tokenizer(regions)
-input_ids = encoded["input_ids"]
-```
-
-`RegionSet` and `Tokenizer` also accept remote inputs in some constructors;
-this skill permits local paths only unless network access is explicitly
-approved. `geniml.io.RegionSet(regions, backed=False)` remains available as a
-legacy Python implementation; backed sets are iterable but not indexable.
-`geniml.io.Region` uses `stop`, while `gtars.models.Region` uses `end`.
-
-With gtars 0.9.2, seven special tokens are added to a BED vocabulary. Therefore
-`len(tokenizer)` is not simply the number of universe rows. Preserve universe
-row order and the exact special-token map.
-
-### Region2Vec
-
-The modern class lives at a concrete module path:
-
-```python
-from geniml.region2vec.main import Region2VecExModel
-from geniml.region2vec.utils import Region2VecDataset
-from gtars.tokenizers import Tokenizer
-
-tokenizer = Tokenizer.from_bed("refs/universe.bed")
-dataset = Region2VecDataset("work/tokens.parquet", shuffle=True)
-model = Region2VecExModel(tokenizer=tokenizer, embedding_dim=100)
-model.train(dataset, epochs=10, window_size=5, num_cpus=4, seed=42)
-```
-
-The Parquet input must contain one list-valued `tokens` column, one document
-per row. See [references/region2vec.md](references/region2vec.md) for export,
-encoding, legacy CLI, and evaluation details.
-
-### scEmbed
-
-Import `ScEmbed` from `geniml.scembed.main`. AnnData `.var` must contain
-`chr`, `start`, and `end`; rows are cells and nonzero features identify
-accessible regions. Pre-tokenize to a Parquet `tokens` column and use the same
-Tokenizer for training and inference. See
-[references/scembed.md](references/scembed.md).
-
-### BEDspace
-
-BEDspace remains in 0.8.4 and invokes an external StarSpace executable.
-StarSpace is archived and upstream Geniml does not pin a compatible revision.
-Treat BEDspace as a legacy reproduction path, not the default for new systems.
-See [references/bedspace.md](references/bedspace.md) for the exact stable CLI
-spelling and an immutable, explicitly unverified build baseline.
-
-### Consensus universes and assessment
-
-The installed 0.8.4 CLI uses:
-
-```text
-geniml build-universe {cc,ccf,ml,hmm} ...
-geniml assess-universe ...
-geniml eval {gdst,npt,ctt,rct,bin-gen} ...
-```
-
-CC/CCF/ML/HMM consume precomputed coverage bigWigs. Do not concatenate or
-generate coverage until all BED files pass the same assembly contract.
-Assessment and embedding metrics are distinct: `assess-universe` measures fit
-of a universe to interval collections, while `eval` implements CTT, RCT, GDST,
-and NPT for embeddings. See
-[references/consensus_peaks.md](references/consensus_peaks.md) and
-[references/utilities.md](references/utilities.md).
-
-## Important 0.8.4 migration notes
-
-- The 0.7.0 changelog moved new RegionSet/tokenizer work toward Gtars.
-- The 0.4.0 names `TreeTokenizer` and `AnnDataTokenizer` are historical; the
-  current Gtars API exposes `Tokenizer`.
-- In the 0.8.4 wheel, `geniml.region2vec` and `geniml.scembed` do not re-export
-  their modern classes/functions. Use the concrete module paths above.
-- `geniml tokenize` and `geniml region2vec` call names no longer exported by
-  their package `__init__` files; do not build new workflows around those CLI
-  paths without an installed-version smoke test.
-- `geniml scembed` parses legacy MatrixMarket options but its command body is a
-  no-op in 0.8.4. Use `geniml.scembed.main.ScEmbed`.
-- Official pages still show `geniml assess`; the release command is
-  `geniml assess-universe`.
-- `.gtok` remains present in legacy datasets, but upstream issue #14 proposes
-  deprecating many-file `.gtok` workflows. Prefer one bounded Parquet corpus.
-- Config key `embedding_size` is accepted only for backward compatibility;
-  use `embedding_dim`.
-
-## Model and universe compatibility
-
-A Region2Vec/scEmbed inference bundle is valid only when these agree:
-
-- model `config.yaml` `vocab_size` and `embedding_dim`;
-- exact `universe.bed` bytes/order and assembly;
-- tokenizer implementation/version and special-token IDs;
-- checkpoint tensor shapes and pooling policy;
-- Geniml/Gtars versions and any tokenization parameters.
-
-Geniml 0.8.4 defaults to `checkpoint.pt`, `config.yaml`, and `universe.bed`.
-Its loader uses `torch.load(..., weights_only=True)`, but `.pt`, Gensim
-`.model`, pickle, joblib, and native binaries remain untrusted inputs. Inspect
-and checksum artifacts before loading; use an isolated environment and never
-load a checkpoint merely to discover its metadata.
-
-```bash
-python skills/geniml/scripts/model_artifact_inspector.py \
-  --model-dir models/region2vec
-
-python skills/geniml/scripts/tokenizer_compatibility.py \
-  --model-dir models/region2vec \
-  --universe refs/universe.bed \
-  --assembly GRCh38
-```
-
-`Region2VecExModel(model_path="org/repo")`, `ScEmbed(model_path="org/repo")`,
-and Gtars `Tokenizer.from_pretrained(...)` can download from Hugging Face.
-Local `from_pretrained("models/local")` loads a local bundle. Pin Hub revision
-and expected hashes when a user approves download; then work offline from the
-verified cache.
-
-## BEDbase downloads and caches
-
-`BBClient.load_bed`, `load_bedset`, and token-cache operations may contact
-`https://api.bedbase.org`. The default cache is
-`$BBCLIENT_CACHE` or `~/.bbcache`; `BEDBASE_API` changes the endpoint. Do not
-read unrelated environment variables. Set an explicit project cache, estimate
-size, approve identifiers/endpoints, and verify returned checksums before use.
-
-Local inspection commands are safer:
-
-```text
-geniml bbclient seek ID --cache-folder /absolute/project/cache
-geniml bbclient inspect-bedfiles --cache-folder /absolute/project/cache
-geniml bbclient inspect-bedsets --cache-folder /absolute/project/cache
-```
-
-The `cache-bed`, `cache-bedset`, and `cache-tokens` subcommands may use the
-network. Do not run them implicitly or include sensitive local BED files in an
-upload/cache workflow.
-
-## Local audit and planning CLIs
-
-All scripts are standard-library-only and default to redacted JSON:
-
-```bash
-# Audit manifest paths, checksums, assemblies, and patient/donor leakage
-python skills/geniml/scripts/corpus_auditor.py \
-  --manifest data/manifest.tsv --assembly-column assembly \
-  --group-column patient_id --split-column split
-
-# Plan tokenizer/model compatibility checks
-python skills/geniml/scripts/tokenizer_compatibility.py \
-  --model-dir models/r2v --universe refs/universe.bed --assembly GRCh38
-
-# Plan consensus construction; does not execute Geniml or coverage tools
-python skills/geniml/scripts/consensus_plan.py \
-  --manifest data/manifest.tsv --chrom-sizes refs/GRCh38.chrom.sizes \
-  --assembly GRCh38 --method cc --output-dir work/consensus
-
-# Plan an embedding run; does not import ML libraries
-python skills/geniml/scripts/embedding_plan.py \
-  --mode region2vec --data work/tokens.parquet \
-  --universe refs/universe.bed --output-dir work/r2v \
-  --assembly GRCh38
-```
-
-Use `--help` for resource limits and explicit path-disclosure controls.
-
-## References
-
-- [Region2Vec](references/region2vec.md): modern API, artifacts, CLI drift,
-  training, encoding, and evaluation.
-- [scEmbed](references/scembed.md): AnnData/token preparation, training,
-  inference, annotation, privacy, and leakage.
-- [BEDspace](references/bedspace.md): metadata schema, exact legacy CLI,
-  StarSpace status, artifacts, and retrieval.
-- [Consensus peaks](references/consensus_peaks.md): coverage prerequisites,
-  CC/CCF/ML/HMM, assessment, and assembly safeguards.
-- [Utilities](references/utilities.md): I/O, Gtars tokenizers, BBClient,
-  evaluation, model safety, migration, and dated sources.
-
-Source snapshot and primary-paper links are dated in
-[references/utilities.md](references/utilities.md). Re-check release metadata
-and installed signatures before changing the pinned versions.