docs/References.md

Table Of Contents

1. References
2. Project Reference
   1. Project Paths
   2. Command Reference
   3. Dependency Surfaces
   4. Environment Variables
   5. Configuration Files
   6. Model Registry
   7. Public Interfaces
   8. Figure Visual Tokens

1. References

Use this file when you need an exact path, command, environment variable, or public name. Use How-To User Guides for procedure and Explanations for concepts.

2. Project Reference

Project Paths

Core paths:

Path	Role
README.md	Short setup entry point and Hugging Face Space README.
AGENTS.md	Local coding and documentation guidance for agents.
pyproject.toml	Package metadata, dependencies, entry points, and tool configuration.
justfile	Development commands.
app.py	Hugging Face Space shim for the Gradio workbench.
src/kneiff	Runtime package source.
src/kneiff_dev	Maintainer-only package helpers.
tests	Test suite.
docs	Long-form project documentation.
docs/assets	Tracked generated documentation figures.
assets/*.IGNORE*	Ignored local diagram scratch files.
experiments/	Ignored local research and one-off probes.

Related: use Development: repository routing before adding files or moving behavior between directories.

Command Reference

Top-level commands:

Command	Role
knf --help	Show the main Kneiff command tree.
knf config --help	Show native AppRC configuration commands.
knf project --help	Show project scaffold, validation, and storage-switching commands.
knf dataset --help	Show dataset preparation commands.
knf model --help	Show model conversion and maintenance utilities.
knf train --help	Show training lifecycle commands.
knf img --help	Show local image utility, tagging, captioning, and upscaling commands.
knf comfy --help	Show ComfyUI server workflow commands.
knf llm --help	Show local LLM commands.
jtp3-wrap --help	Run the optional direct JTP-3 wrapper entry point with the same selected-tag output modes.

Root AppRC options must appear before the command group:

Option	Role
--env-file PATH	Load one explicit dotenv file before runtime config. Repeat the option to load multiple files.
--env-file-overrides-os-environ, -o	Let explicit dotenv values override existing process environment values for this invocation.
--skip-dotenv-layers, -s	Select storage without merging packaged, app-wide, storage-local, or explicit dotenv values into the process environment.
--storage NAME_OR_PATH	Select a registered storage name or storage path for this invocation.
--log-level LEVEL	Configure logging before AppRC runtime bootstrap.

Runtimeful dataset, training, ComfyUI, and LLM actions require explicit storage selection through KNF_STORAGE or --storage. A lone registered storage is not auto-selected. The selected AppRC root is the project root. Explicit configs/*.knf.yaml paths must remain inside it; select another project with --storage before using that project's config. knf project init is runtime-independent and does not accept root --env-file; export KNF_APPRC_TOML directly when the registry path must be overridden.

Config commands:

Command	Role
knf config paths [--json]	Show declared and active AppRC paths without writing files.
knf --storage NAME_OR_PATH config show [--json]	Show resolved AppRC paths, capabilities, and active storage.
knf config doctor [--json]	Check AppRC readiness and report exact setup actions.
knf config setup --yes --storage-root PATH	Create the app-wide and storage-local dotenv files non-interactively.
knf --storage NAME_OR_PATH config set KEY VALUE --scope app|storage	Validate and write one override to the selected AppRC layer.
knf --storage NAME_OR_PATH config edit	Open the Textual TUI for AppRC dotenv overrides.
knf config app init	Create ~/.config/knf/.env.apprc-app.
knf config storage add NAME PATH --yes	Register a persistent storage root in ~/.config/knf/knf.apprc.toml and create its .env.apprc-storage file.
knf config storage list	Show registered storage roots and active-selector markers.
knf config storage list --json	Emit the storage registry as JSON.
knf config storage remove NAME	Remove a named storage entry.

Project commands:

Command	Role
knf project init PATH [--name NAME] [--activation-token TOKEN --species-token TOKEN] [--git-user-name NAME] [--yes]	Preflight, create, and validate the complete Sygred scaffold: root vocabulary.knf.yaml, prompts.knf.yaml, default_tags.txt, .gitignore, .gitattributes, configs/ANIMA.knf.yaml, configs/F2K_9B.knf.yaml, SOURCE/0-FULLBODY/, SOURCE/2-HEAD/, empty HF//TRAINING/, and .old_manifests/; initialize a new root as a main Git repository with local user.name defaulting to kneiff; and register the root with AppRC, which creates .env.apprc-storage. Both generated configs are validated through Kneiff's export and SimpleTuner loaders but accept empty source folders. Existing project files and existing Git identity/remotes are not replaced. The command never sets Git email/global settings, creates a commit, or installs/configures Git LFS.
knf project list [--json]	Parse the resources in every registered AppRC storage and report ready, invalid, or missing root.
knf project show [--json]	Show the selected project root, identity, validation status, default Anima and Flux2 configs, default tags, Git files/repository state, starter source directories, and conventional resource paths.
knf project validate	Validate both fixed starter configs, starter source directories, Git/default-tag files, vocabulary, and prompt/workflow resources; then report the activation token, species token, core/project/resolved prompt counts, and workflow-override count.
knf project use NAME	Persist KNF_STORAGE=NAME as the app-wide fallback. A shell KNF_STORAGE or root --storage overrides it.

Dataset commands:

Command	Role
knf dataset plan CONFIG...	Print the compact CONFIG id, resolved config path, project root, source root, manifest path, export root, and export subsets for one or more configs.
knf dataset describe CONFIG...	Print dry-run export tables with per-subset counts and SimpleTuner sampling columns without writing files.
knf dataset aspects CONFIG [--processes N]	Build a caption-free geometry plan, then print each active SimpleTuner backend's deterministic aspect buckets, raw and repeat-expanded counts, physical-pruning status, effective-batch launch compatibility, and prospective safe-border repairs. It validates mapped source paths and image geometry plus configured resize, mirror, and caption-output multiplicity, but never loads a vocabulary or validates caption tags/axes. --processes defaults to 1 and must match the Accelerate process count. It never changes images, manifests, HF exports, or training workspaces; it only maintains .old_manifests/_aspect_cache/<config-id>.json, which is invalidated by config, manifest, source, and repair-policy changes. Progress and the human report use stderr. Stdout is only a deduplicated newline-delimited stream of physically pruned SOURCE/<path> images, suitable for knf dataset aspects CONFIG | knf comfy outpaint -w willy; launch-blocking buckets are not misreported as excluded images. A later real export can still omit images with invalid caption semantics. Random aspect-crop configurations are rejected because no exact static assignment exists.
knf dataset sync CONFIG...	Sync MANIFEST.knf.xlsx and generated MANIFEST.yaml from SOURCE/, incrementally reconcile each config-derived dataset in HF/<config-id>/, refresh Hugging Face artifacts, and write non-mirrored export image grids when image outputs changed or the grid is missing. After a successful export, it caches an authoritative one-process safe-border repair plan and warns about PRUNED/INCOMPATIBLE buckets. It never changes SOURCE or HF pixels.
knf dataset readme CONFIG...	Rewrite export-root README.md files from existing metadata and optional existing SimpleTuner JSON.
knf dataset sync CONFIG... --manifest-only	Refresh only MANIFEST.knf.xlsx and generated MANIFEST.yaml using paths derived from each config.
knf dataset sync CONFIG... --dry-run	Validate and count outputs without writing files, including source/export and SimpleTuner resolution planning.
knf dataset sync CONFIG... --verbose	Show all changed-image rows and all uncapped resolution buckets instead of capped sync feedback.
knf dataset sync CONFIG... --rebuild	Delete all public export contents before writing the planned dataset outputs.
knf dataset sync CONFIG... --rebuild --yes	Confirm the destructive rebuild prompt without asking.
knf dataset sync CONFIG... --exclude PATTERN	Add a manifest exclusion glob relative to SOURCE/.
knf dataset grid CONFIG...	Write non-mirrored kneiff-training-image-grid.jpg files from existing export roots without exporting.
knf dataset grid CONFIG --output PATH	Write one training image grid to an explicit path. --output is rejected with multiple configs.

For dataset commands and batch-capable training commands, CONFIG... can be omitted in an interactive terminal. Kneiff opens an arrow-key picker when multiple direct child configs/*.knf.yaml files exist in the active storage root, and ambiguous typed selectors open a picker limited to matching configs. Use Space to toggle configs, a to toggle all, Enter to confirm, and q/Esc to cancel. Non-interactive scripts should pass explicit config paths or selectors.

Model commands:

Command	Role
knf model convert --family sdxl SOURCE [OUTPUT]	Convert a local SDXL .safetensors or .ckpt checkpoint into a Diffusers directory while preserving full single-file pipeline components such as text encoders. Default OUTPUT is a sibling <source-stem>Diffusers directory. Existing valid Diffusers directories are reused; invalid existing output paths fail.

ComfyUI commands:

Command	Role
knf comfy showcase [--lora LORA|--training/-t [STEPS]...] [--prompts YAML] [-w WORKFLOW] [--prompt-field FIELD]	Queue a showcase collection through a running ComfyUI API server. Omit --prompts to use the selected project's resolved core-plus-overlay catalog; an explicit version-1 YAML path is a standalone collection. --lora is a path below $COMFY_MODELS_DIR/models/loras; omit it in an interactive terminal to pick one. --training / -t instead opens a flat multi-picker over .safetensors files in direct TRAINING/<config-id>_<run>/_simpletuner-output/ trees; optional positive STEPS match exact checkpoint-<step> directories, and every requested step must exist. ComfyUI-native files sort first without hiding raw files. Checked files are hard-linked, or copied across filesystems, into unique .kneiff-training directories below models/loras and removed after the run. All selected LoRAs use one workflow; omitted WORKFLOW is inferred from the first selected path, with the full workflow picker as the TRAINING fallback. -t requires an interactive terminal and conflicts with --lora. Set COMFY_LORAS_DIR_1 to choose the regular picker start directory. Scripts should pass --workflow PRESET, --workflow auto, or an API-format workflow JSON path. Project overrides use workflows/showcase_<preset>.workflow.json and take precedence over packaged presets with the same name. The command prints prompt sources, inspected workflow configuration, output paths, and aggregate progress. Individual images stay in the dated ComfyUI SaveImage directory. Every successful run uploads a timestamped JPEG grid into that same output subfolder, with prompts as columns, LoRAs as rows, and prompt labels repeated above and below with a ten-line maximum. No showcase grid is written below TRAINING.
knf comfy upscale INPUT... [--model MODEL] [--style photoreal|shaded|flat] [--lora LORA --token TOKEN] [--lora-strength FLOAT] [--denoise-base FLOAT|-d FLOAT] [--seed SEED] [-z|--z-image] [--fast]	Upload one image or directory of images to a running ComfyUI API server. By default, run a two-stage Krea2 quality pipeline that creates two seed branches per stage and saves four final candidates through builtin SaveImage under dated prefixes such as 26-06-23/260623-11_15_14-upscale-image-c1. Built-in Krea2 defaults use 4x-UltraSharpV2.pth, krea2_turbo_fp8_scaled.safetensors, qwen3vl_4b_fp8_scaled.safetensors, krea2, and qwen_image_vae.safetensors; matching COMFY_* env vars override them. COMFY_UPSCALE_LORA resolves through COMFY_MODELS_DIR and COMFY_LORAS_DIR_1; COMFY_UPSCALE_LORA_TOKEN is optional and only prepends prompt text. --denoise-base / -d replaces the formula base while keeping automatic stage adjustments. Interactive terminals open a picker when a non-explicit default/configured value is unavailable. Pass -z / --z-image for the legacy Z-Image quality workflow, or --fast for the single-pass LoadImage -> UpscaleModelLoader -> ImageUpscaleWithModel -> SaveImage workflow without refiner settings.
knf comfy outpaint [IMAGES...] [--safe-border] [-a|--from-pruned-aspects] [--aspects-config CONFIG] [-w willy|stablemondai-sdg] [--seed SEED] [--url URL] [--square-fraction FLOAT]	Extend explicit image files, or omitted-input newline-delimited SOURCE/<path> stdin from knf dataset aspects; an empty stream succeeds. -a / --from-pruned-aspects calculates physically pruned sources in-process with --aspects-config CONFIG and cannot combine with image arguments or stdin. --square-fraction is in (0, 1]; its 0.25 default is gentle and 1.0 fully squares non-square inputs. Default mode uploads files to a running ComfyUI server, uses a packaged core-node masked workflow, and requires -w outside a terminal; its source region is restored after sampling and Ctrl-C cancels only prompts owned by this invocation. --safe-border instead runs entirely locally: it preserves EXIF-corrected source pixels, edge-extends and progressively blurs only new outer pixels, and writes collision-safe lossless PNGs below the required COMFY_OUTPUT_DIR. Safe mode requires neither ComfyUI nor -w, accepts the same three input modes, prints bare output paths to stdout, and rejects --workflow, --url, and --seed.
knf comfy t2i solo TEXT [--pipeline krea2|krea2-flux2|anima-flux2] [OPTIONS]	Generate reviewed one-character LM Studio variations from the positional scene request. An interactive terminal opens a required three-choice pipeline picker when --pipeline is omitted; scripts must pass it. krea2 queues fixed 1024x1024 Krea2 finals directly. krea2-flux2 queues Krea2 baselines then Flux2 Klein 9B cleanup candidates; anima-flux2 does the same with one-LoRA Anima baselines. Defaults are three prompts and three images per prompt; Flux profiles also default to three cleanup candidates per baseline. CLI options can override stage models, LoRAs, strengths, counts, optional local mirror, ComfyUI URL, root seed, and participant 1 activation token for one run.
knf comfy t2i duo TEXT [OPTIONS]	Generate reviewed duo variations from the positional scene request, immediately queue all fixed 1024x1024 Anima baseline branches, wait for every baseline, then upload them into a run-specific ComfyUI input subfolder and queue all Flux2 Klein 9B distilled cleanup branches. Defaults produce nine baselines and 27 finals. CLI options can override both activation tokens, T2I and I2I models, both stage LoRAs and strengths, counts, optional local mirror, URL, and root seed for one run.

ComfyUI progress renders on stderr only in interactive terminals. Showcase uses one unit per eligible prompt and selected LoRA. Fast upscale and outpaint use one unit per image; quality upscale uses six units per image for its two intermediate and four final prompts. Redirected stdout retains its existing plain result lines.

T2I runs use three prompt, baseline, and cleanup progress tasks. Redirected output prints deterministic stage messages. Output paths are:

<ComfyUI-output>/<YY-MM-DD>/<timestamp>-t2i-<solo|duo>/
├── baselines/                  # Flux cleanup profiles and duo only
├── final/
└── run.knf.yaml

Manifest schema version 1 records the run status, composition pipeline and selected model-stage profile, timestamps, counts, 1024x1024 resolution, root seed, original request, raw and effective prompts, activation-token slots, ComfyUI-visible models and LoRAs, strengths, every job's coordinates and derived seed, prompt id, status, relative output path, actual ComfyUI output reference, and compact error. It contains no API key, environment dump, or absolute machine path and is not accepted as resume input.

LLM commands:

Command

Role

knf llm prompt "SCENE" [--model MODEL] [--draft-model MODEL] [--review-model MODEL] [--base-url URL] [--field FIELD=VALUE] [--format json|text|review] [--verbose] [--text] [--no-export] [--no-review] [--save-exchanges]

Generate a two-pass image prompt through a running LM Studio OpenAI-compatible server. Human review output is the default and prints the first version, second version, and comments. --verbose and --format json print the full structured JSON payload with dataset-shaped fields, final prompts, assumptions, missing input, review issues, and model ids. --format text and --text print only copy-friendly final prompt text. User-facing JSON and review text are saved below .llm_promptgen/results/ in the selected storage by default; --no-export suppresses them. Repeat --field to force manifest-compatible values from the selected project vocabulary, such as character=Character_Token, view=rear_view, or pose_body=standing,leaning. --save-exchanges writes raw debug transcripts below .llm_promptgen/ unless KNF_PROMPTGEN_EXCHANGE_DIR overrides the location.

The former --export opt-in is removed. Result export is storage-backed and on by default; use --no-export for terminal-only output.

Packaged Comfy workflow policy:

• Store Comfy graphs as API-format JSON templates below src/kneiff/infer/comfy/resources/workflows/**.
• Python may patch placeholders, remove optional nodes, and rewire dynamic edges, but full Comfy graphs should live in packaged templates unless a documented exception is needed.
• Packaged KSampler nodes must set control_after_generate to fixed so seed reproduction survives optimization passes.
• --debug-write-workflows DIR writes fully patched executable workflows for inspection.

Packaged workflow and project resource starter files:

Path	Role
src/kneiff/infer/comfy/resources/workflows/showcase/showcase_anima.workflow.json	anima preset API workflow template with Kneiff placeholders for LoRA name, prompt, negative prompt, filename prefix, and seed. It passes the 50-step baseline latent through a seed-43, 30-step, CFG 4, dpmpp_2m_sde_gpu, beta, 0.4-denoise refiner before decoding.
src/kneiff/infer/comfy/resources/workflows/showcase/showcase_anima-novafurryam.workflow.json	anima-novafurryam preset API workflow template using the selected LoRA and Nova Furry AM v3.0 ANIMA model with the same baseline settings as anima.
src/kneiff/infer/comfy/resources/workflows/showcase/showcase_pony.workflow.json	pony preset API workflow template using the selected LoRA and Pony prompt-field default.
src/kneiff/infer/comfy/resources/workflows/showcase/showcase_noob-willy.workflow.json	noob-willy preset API workflow template using the selected LoRA, RescaleCFG 0.5, the resolved NOOB negative prompt, and 50-step, CFG 5.5, Euler ancestral, beta sampling.
src/kneiff/infer/comfy/resources/workflows/showcase/showcase_noob-chenkin.workflow.json	noob-chenkin preset API workflow template using the selected LoRA, NOOB prompt-field default, and 60-step beta res_multistep sampling.
src/kneiff/infer/comfy/resources/workflows/showcase/showcase_noob-base.workflow.json	noob-base preset API workflow template using the selected LoRA, NOOB prompt-field default, and 50-step beta Euler sampling.
src/kneiff/infer/comfy/resources/workflows/showcase/showcase_noob-nova.workflow.json	noob-nova preset API workflow template using the selected LoRA, NOOB prompt-field default, and 60-step beta res_multistep sampling.
src/kneiff/infer/comfy/resources/workflows/showcase/showcase_noob-scrimblosauce.workflow.json	noob-scrimblosauce preset API workflow template using the selected LoRA, NOOB prompt-field default, and 70-step Karras uni_pc sampling.
src/kneiff/infer/comfy/resources/workflows/showcase/showcase_noob-stablemondai-sdg.workflow.json	noob-stablemondai-sdg preset API workflow template using the selected LoRA, RescaleCFG 0.5, the resolved NOOB negative prompt, and Euler ancestral, SGM Uniform, 32-step, CFG 5.0 sampling.
src/kneiff/infer/comfy/resources/workflows/showcase/showcase_flux2-klein-4b.workflow.json	flux2-klein-4b preset API workflow template using the selected LoRA and non-base Flux2 Klein 4B model with distilled 4-step, CFG 1, empty negative-prompt settings.
src/kneiff/infer/comfy/resources/workflows/showcase/showcase_flux2-klein-9b.workflow.json	flux2-klein-9b preset API workflow template using the selected LoRA and non-base Flux2 Klein 9B model with distilled 4-step, CFG 1, empty negative-prompt settings.
src/kneiff/infer/comfy/resources/workflows/showcase/showcase_flux2-klein-base-4b.workflow.json	flux2-klein-base-4b preset API workflow template using the selected LoRA and Flux2 Klein Base 4B model with 40-step, CFG 5.0, res_multistep, empty negative-prompt settings.
src/kneiff/infer/comfy/resources/workflows/showcase/showcase_flux2-klein-base-9b.workflow.json	flux2-klein-base-9b preset API workflow template using the selected LoRA and Flux2 Klein Base 9B fp8 model with 40-step, CFG 5.0, res_multistep, empty negative-prompt settings.
src/kneiff/infer/comfy/resources/workflows/showcase/showcase_z-image-turbo.workflow.json	z-image-turbo preset API workflow template using the selected LoRA and Z-Image Turbo bf16 model with 8-step, CFG 1, res_multistep, simple sampling.
src/kneiff/infer/comfy/resources/workflows/showcase/showcase_krea2-turbo.workflow.json	krea2-turbo preset API workflow template using the selected LoRA and the local Krea2 Turbo FP8 model with 8-step, CFG 1, Euler, simple sampling.
src/kneiff/infer/comfy/resources/workflows/t2i/solo_generation.workflow.json	Fixed 1024x1024 Krea2 Turbo solo graph with model, LoRA, strength, positive prompt, seed, and filename placeholders.
src/kneiff/infer/comfy/resources/workflows/t2i/solo_anima_generation.workflow.json	Fixed 1024x1024 Anima solo graph with one model-only LoRA, positive and negative prompts, and duo-aligned sampling settings.
src/kneiff/infer/comfy/resources/workflows/t2i/solo_cleanup.workflow.json	Fixed 1024x1024, 4-step Flux2 Klein 9B distilled one-character image-edit graph with one model-only LoRA and the workflow-owned full_encoder_small_decoder.safetensors VAE.
src/kneiff/infer/comfy/resources/workflows/t2i/duo_generation.workflow.json	Fixed 1024x1024 Anima graph with two chained LoraLoaderModelOnly nodes and positive, negative, seed, and filename placeholders.
src/kneiff/infer/comfy/resources/workflows/t2i/duo_cleanup.workflow.json	Fixed 1024x1024, 4-step Flux2 Klein 9B distilled image-edit graph using core LoadImage, VAEEncode, and ReferenceLatent conditioning, two chained model-only LoRAs, CFG 1, Euler, and Flux2Scheduler. The workflow-owned VAE is full_encoder_small_decoder.safetensors.
vocabulary.knf.yaml	Selected project's strict kneifftags.vocabulary-extension schema-version-2 document. It declares a unique namespace, ordered character and species identities, and optional project categories, groups, tags, and explicit built-in overrides. Identity and tag definitions can own output tags, aliases, natural/NLG phrases, Chroma tags, ordering, and Kneifftags safety metadata. Kneifftools composes the validated extension with the built-in Kneifftags vocabulary in an isolated engine. A schema-version-1 file is accepted only by the transactional dataset migration.
src/kneiff/prompts/resources/core_prompts.knf.yaml	Packaged version-1 prompt baseline: portable character reference, worst quality NOOB negative default, and immutable fixed negative controls. ${character} and ${species} expand only in this package resource.
prompts.knf.yaml	Optional strict version-1 project overlay on the packaged prompt catalog. Project scalar defaults replace core defaults; negative_prompts override by field, including NOOB showcase runs. showcase_model_prompts merges each model family's positive_prefix and negative_prefix independently and applies them only during ComfyUI showcase generation; the negative prefix prepends to the resolved row or catalog negative base. ignore_positive_prefix: true on a row skips model and field positive prefixes. showcase_positive_prefixes remains a field-keyed fallback. A same-ID row fully replaces a core row. Every row requires nonempty uses; project rows cannot use or replace negative_control.
workflows/showcase_<preset>.workflow.json	Optional selected-project ComfyUI showcase workflow. It must be a regular API-format JSON file with prompt, seed, and filename-prefix placeholders; filename-derived IDs are lowercased with _ separators normalized to -, are never remapped through packaged aliases, and must be unique after normalization. Known IDs select their built-in model family; every other ID selects the same showcase_model_prompts key.
src/kneiff/prompts/resources/lmstudio/base_prompt.yaml	Packaged first-pass LM Studio prompt-generation template.
src/kneiff/prompts/resources/lmstudio/review_prompt.yaml	Packaged second-pass LM Studio consistency review template.

Packaged upscale starter files:

Path	Role
src/kneiff/infer/comfy/resources/workflows/upscale/upscale_fast.workflow.json	API workflow template for knf comfy upscale --fast; Kneiff patches image, upscale model, and output prefix placeholders.
src/kneiff/infer/comfy/resources/workflows/upscale/upscale_krea2_quality_stage.workflow.json	Default Krea2 API workflow template for each quality upscale stage; Kneiff patches dimensions, refiner models, prompt, seed, denoise, model-only LoRA values, and output mode. Krea2 quality upscale does not use TiledDiffusion.
src/kneiff/infer/comfy/resources/workflows/upscale/upscale_quality_stage.workflow.json	Legacy Z-Image API workflow template used by knf comfy upscale -z; Kneiff patches dimensions, refiner models, prompt, seed, denoise, LoRA values, output mode, and optional TiledDiffusion.

ComfyUI-visible model names required by the packaged showcase presets:

Preset	Required model files
anima	diffusion_models/Anima/anima-base-v1.0.safetensors, text_encoders/qwen_3_06b_base.safetensors, vae/qwen_image_vae.safetensors, plus the selected --lora below models/loras.
anima-novafurryam	diffusion_models/Anima/novaFurryAM_v30.safetensors, text_encoders/qwen_3_06b_base.safetensors, vae/qwen_image_vae.safetensors, plus the selected --lora below models/loras.
pony	checkpoints/_base_finetunes/ponyDiffusionV6XL_v6StartWithThisOne.safetensors, plus the selected --lora below models/loras.
noob-willy	checkpoints/_base_finetunes/willysRealism_coreV1.safetensors, plus the selected --lora below models/loras.
noob-base	checkpoints/_base_finetunes/noobaiXLNAIXL_epsilonPred11Version.safetensors, plus the selected --lora below models/loras.
noob-chenkin	checkpoints/_base_finetunes/chenkinNoobXLCKXL_v05.safetensors, plus the selected --lora below models/loras.
noob-nova	checkpoints/novaFurryXL_ilV180A.safetensors, plus the selected --lora below models/loras.
noob-scrimblosauce	checkpoints/SDXL-realistic/scrimbloSauceXL_v80NAI.safetensors, plus the selected --lora below models/loras.
noob-stablemondai-sdg	checkpoints/stablemondaiSDG_v10.safetensors, plus the selected --lora below models/loras.
flux2-klein-4b	diffusion_models/F2K_4B/flux-2-klein-4b.safetensors, text_encoders/qwen_3_4b.safetensors, vae/flux2-vae.safetensors, plus the selected --lora below models/loras.
flux2-klein-9b	diffusion_models/F2K_9B/flux-2-klein-9b.safetensors, text_encoders/qwen_3_8b_fp8mixed.safetensors, vae/flux2-vae.safetensors, plus the selected --lora below models/loras.
flux2-klein-base-4b	diffusion_models/F2K_4B/flux-2-klein-base-4b.safetensors, text_encoders/qwen_3_4b.safetensors, vae/flux2-vae.safetensors, plus the selected --lora below models/loras.
flux2-klein-base-9b	diffusion_models/F2K_9B/flux-2-klein-base-9b-fp8.safetensors, text_encoders/qwen_3_8b_fp8mixed.safetensors, vae/flux2-vae.safetensors, plus the selected --lora below models/loras.
z-image-turbo	diffusion_models/ZI_Turbo/z_image_turbo_bf16.safetensors, text_encoders/qwen_3_4b.safetensors, vae/ae.safetensors, plus the selected --lora below models/loras.
krea2-turbo	diffusion_models/Krea2/krea2_turbo_fp8.safetensors, text_encoders/qwen3vl_4b_fp8_scaled.safetensors, vae/qwen_image_vae.safetensors, plus the selected --lora below models/loras.

Training commands:

Command	Role
knf train start CONFIG...	Require a populated HF/<config-id>/ from knf dataset sync, prepare the next free run for each config, show the artifact review menu with SimpleTuner resolution behavior and current safe-border aspect-repair readiness in interactive terminals, launch SimpleTuner sequentially, and write final validation grids after success.
knf train start CONFIG... --yes	Launch without the interactive review gate.
knf train start CONFIG... --no-review	Launch without showing generated JSON review.
knf train start CONFIG... --resume N	Validate the prepared run's copied dataset and launch existing not_started or incomplete run N for each config without regenerating artifacts from YAML.
knf train start CONFIG --resume	Open an interactive picker for resumable runs. In a batch, bare --resume prompts once per config.
knf train extend CONFIG_OR_SELECTOR RUN --steps N / -s N	Continue an existing complete, failed, or incomplete run in place by increasing generated max_train_steps by N, setting resume_from_checkpoint to latest, patching source YAML training.simpletuner.trainer.max_train_steps after confirmation, and launching from the latest numeric checkpoint.
knf train start CONFIG... --testrun	Apply training.simpletuner.trainer_testrun while preparing fresh runs.
knf train start CONFIG... --cuda-device 1	Select the visible CUDA device for SimpleTuner.
knf train start CONFIG... --fallback-cuda-device 0	Record a fallback CUDA device for launch wrappers.
knf train prepare CONFIG...	Require a populated HF/<config-id>/ from knf dataset sync, validate or rebuild its authoritative aspect-repair cache, and prepare new not_started runs without launching SimpleTuner. Safe planned repairs replace only files in the new dataset/ copy; byte-identical review copies appear in _knf_aspect_repair/ beside it. It reports whether all known PRUNED/INCOMPATIBLE assignments are covered and lists any variants that exceed the 180-pixel automatic-padding limit. Resumed runs remain unchanged.
knf train promote --name NAME / -n NAME	Interactively choose a numeric checkpoint from TRAINING, a destination below COMFY_MODELS_DIR/models/loras, and a mandatory release version. Preview, confirm, then atomically copy the source without overwrite as <name>-<MODEL_ID>-v<major>.<minor>-<step>.safetensors; name defaults to custom_tokens.character.text.
knf train runs CONFIG_OR_SELECTOR	List discovered run numbers, statuses, timestamps, and output directories.
knf train review CONFIG_OR_SELECTOR N	Review generated JSON artifacts for an existing run without launching.
knf train grid CONFIG_OR_SELECTOR N	Write TRAINING/<config-id>_<run>-kneiff-validation-progress-grid.jpg from existing SimpleTuner validation images.
knf train grid CONFIG_OR_SELECTOR N --output PATH	Write the validation progress grid to an explicit path.

run_simpletuner_training() has one launch implementation: it resolves the absolute Python interpreter declared by the installed simpletuner entry point and runs python -m kneiff_simpletuner_runner from the numbered workspace. build_simpletuner_launch_environment() returns the child environment. Neither API accepts an executable override or an in-process launch switch.

For SDXL configs, training.simpletuner.model.pretrained_model_name_or_path must point at a Diffusers directory. knf train prepare CONFIG fails with the matching knf model convert --family sdxl ... command when it finds a local top-level .safetensors or .ckpt checkpoint. knf train start CONFIG can run that conversion after confirmation, or automatically with --yes, then updates the source YAML so future starts use the converted directory. Conversion loads the full single-file SDXL pipeline and then saves the configured VAE override. After successful SDXL/Pony LoRA training, knf train start CONFIG also writes a ComfyUI-compatible sibling LoRA named pytorch_lora_weights.comfyui.safetensors beside each SimpleTuner pytorch_lora_weights.safetensors checkpoint.

Image commands:

Command	Role
knf img png2jpg INPUT_DIR	Convert PNG files below a directory to JPEG.
knf img concat IMAGE... --output out.png	Concatenate images horizontally.
knf img rename PATH... --base-name NAME	Rename image files with a prefix or enumerated random suffix.
knf img upscale INPUT... --out-dir PATH	Upscale one image or a directory of images.
knf img tag PATH... --recursive	Print RedRocket/JTP-3 tags as e621-style whitespace-separated text.
knf img tag PATH... --recursive --txt	Write RedRocket/JTP-3 .txt tag sidecars.
knf img tag PATH... --recursive --txt --comma	Write legacy comma-separated RedRocket/JTP-3 tag sidecars.
knf img tag PATH... --csv-stdout	Print RedRocket/JTP-3 probability CSV output.
knf img caption TARGET --server --model-name MODEL	Caption an image or directory through an OpenAI-compatible server.
knf img caption TARGET --blip --model-name MODEL	Caption an image or directory through the BLIP/Qwen path.

png2jpg, local upscale, and directory caption use the shared interactive progress renderer. Directory caption totals exclude existing sidecars unless --overwrite is active. Progress is written to stderr; redirected stdout keeps legacy result and dry-run lines without ANSI codes. concat, rename, tag, and single-image captioning do not create a Kneiff progress display.

knf img tag selected-tag output:

Mode	Command	Output
Default stdout	knf img tag IMAGE	One e621-style whitespace-separated tag line.
Multi-image stdout	knf img tag IMAGE... or knf img tag DIR --recursive	One PATH<TAB>TAGS line per image.
Sidecar files	knf img tag PATH... --txt	.txt sidecars next to images, e621-style by default.
Legacy selected tags	knf img tag PATH... --comma or knf img tag PATH... --txt --comma	Comma-separated selected-tag text.
Probability CSV	knf img tag PATH... --csv-stdout	Upstream probability CSV; incompatible with --txt and --comma.

knf img tag options:

The current RedRocket/JTP-3 main snapshot requires pyvips plus native libvips. Install Python dependencies with uv sync or .venv/bin/python -m pip install -e .. On Fedora WSL, install native libvips with sudo dnf install vips. Current main uses calibrated upstream tag selection; --threshold is only for legacy pinned revisions.

Option	Meaning
PATHS...	Image files or directories. Directory inputs require --recursive to include nested images.
--recursive, -r	Scan directory inputs recursively.
--threshold, -t FLOAT	Symmetric JTP-3 tag threshold for legacy pinned revisions. Default: 0.2. Current main rejects non-default thresholds.
--device, -d TEXT	Torch device, such as cuda, cuda:1, or cpu.
--batch-size, -b INTEGER	Images per inference batch. Default: 1.
--workers, -w INTEGER	Upstream image-loader workers. Omit to use JTP-3's automatic worker count.
--seqlen, -S INTEGER	NaFlex sequence length. Default: 1024. Accepted upstream range: 64 to 2048.
--prefix, -p TEXT	Tag text forced to the beginning of selected-tag output.
--txt	Write selected tags to .txt sidecars instead of stdout.
--comma, -c	Use legacy comma-separated selected-tag text.
--csv-stdout	Print probability CSV output instead of selected-tag text.
--repo-id TEXT	Hugging Face model repository. Default: RedRocket/JTP-3.
--revision TEXT	Hugging Face branch, tag, revision, or commit.

Maintainer commands:

Command	Role
just --list	Show available development recipes.
just sync	Sync the full maintainer environment from uv.lock.
just lock	Resolve dependencies and refresh pylock.toml.
just upgrade	Relock with upgrades, then sync.
just clean	Remove caches and build artifacts.
.venv/bin/ruff format .	Format Python files.
.venv/bin/ruff check .	Lint Python files.
.venv/bin/pyright	Type-check Python files.
.venv/bin/pytest	Run the test suite.

Related: use How-To User Guides: run tests for the command sequence.

Dependency Surfaces

Dependency locations:

Surface	File Section	Use
Runtime dependencies	[project].dependencies	Packages required by normal users.
Dependency groups	[dependency-groups]	Local maintainer tools such as tests, linting, typing, docs, and profiling.
Lock file	uv.lock	Reproducible uv installs.
Exported lock	pylock.toml	Python lock export generated by just lock.

Related: use dependency model for why runtime dependencies and maintainer-only tools stay separate.

Environment Variables

Common environment variables:

Name	Role
KNF_APPRC_TOML	Optional AppRC registry path override. Defaults to ~/.config/knf/knf.apprc.toml.
KNF_STORAGE	Required active storage selector for runtimeful commands. The value may be a registered name or a path; AppRC does not auto-select a lone registry entry.
COMFY_URL	ComfyUI API server URL. Defaults to http://127.0.0.1:8188.
COMFY_MODELS_DIR	ComfyUI models root containing models/loras for T2I resolution and showcase LoRA discovery. models/loras must be writable for temporary --training / -t staging and must belong to the running ComfyUI server. Example: /path/to/comfyui-models.
COMFY_LORAS_DIR_1	Primary LoRA subdirectory used by solo T2I, duo participant 1, showcase picker startup, and COMFY_UPSCALE_LORA. Relative values resolve below $COMFY_MODELS_DIR/models/loras; absolute values must also be below that root.
COMFY_LORAS_DIR_2	Partner LoRA subdirectory used by duo participant 2. It follows the same relative or root-contained absolute path rules as COMFY_LORAS_DIR_1.
COMFY_OUTPUT_DIR	Required local output root for knf comfy outpaint --safe-border; it receives dated lossless PNG repairs. It is also the optional local mirror root for downloaded T2I files and manifests. Blank values leave ordinary ComfyUI results server-managed, but make --safe-border unavailable. --output-dir overrides this key for one T2I run.
COMFY_T2I_MODEL_SOLO	Required ComfyUI-visible Krea2 generation UNET for solo. A leading diffusion_models/ is optional; Kneiff submits the form reported by ComfyUI.
COMFY_T2I_LORA_SOLO	Required solo generation LoRA below COMFY_LORAS_DIR_1. A missing .safetensors suffix is accepted when the suffixed file exists.
COMFY_T2I_LORA_STRENGTH_SOLO	Solo generation model-only LoRA strength. Defaults to 1.0.
COMFY_I2I_MODEL_SOLO	Required ComfyUI-visible Flux2 Klein 9B cleanup UNET for solo --pipeline krea2-flux2 and solo --pipeline anima-flux2.
COMFY_I2I_LORA	Required single-character solo cleanup LoRA below COMFY_LORAS_DIR_1.
COMFY_I2I_LORA_STRENGTH	Solo cleanup LoRA strength. Defaults to 1.0.
COMFY_T2I_MODEL_DUO	Required ComfyUI-visible Anima generation UNET for duo and solo --pipeline anima-flux2.
COMFY_T2I_LORA_DUO_1	Required duo participant 1 and Anima solo generation LoRA below COMFY_LORAS_DIR_1.
COMFY_T2I_LORA_DUO_2	Required duo participant 2 generation LoRA below COMFY_LORAS_DIR_2.
COMFY_T2I_LORA_STRENGTH_DUO_1	Duo participant 1 and Anima solo generation LoRA strength. Defaults to 1.0.
COMFY_T2I_LORA_STRENGTH_DUO_2	Duo participant 2 generation LoRA strength. Defaults to 1.0.
COMFY_I2I_MODEL_DUO	Required ComfyUI-visible Flux2 Klein 9B distilled cleanup UNET for duo.
COMFY_I2I_LORA_1	Required duo participant 1 cleanup LoRA below COMFY_LORAS_DIR_1.
COMFY_I2I_LORA_2	Required duo participant 2 cleanup LoRA below COMFY_LORAS_DIR_2.
COMFY_I2I_LORA_STRENGTH_1	Duo participant 1 cleanup LoRA strength. Defaults to 1.0.
COMFY_I2I_LORA_STRENGTH_2	Duo participant 2 cleanup LoRA strength. Defaults to 1.0.
COMFY_UPSCALE_MODEL	ComfyUI-visible upscale model filename used by knf comfy upscale when --model is omitted. Defaults to 4x-UltraSharpV2.pth.
COMFY_UPSCALE_REFINER_UNET	ComfyUI-visible UNET filename for quality knf comfy upscale. Defaults to krea2_turbo_fp8_scaled.safetensors; -z uses ZI_Turbo/z_image_turbo_fp8_e4m3fn.safetensors when this value is not explicitly configured.
COMFY_UPSCALE_REFINER_CLIP	ComfyUI-visible CLIP filename for quality knf comfy upscale. Defaults to qwen3vl_4b_fp8_scaled.safetensors; -z uses qwen_3_4b.safetensors when this value is not explicitly configured.
COMFY_UPSCALE_REFINER_CLIP_TYPE	CLIPLoader type for quality knf comfy upscale. Defaults to krea2; -z uses lumina2 when this value is not explicitly configured.
COMFY_UPSCALE_REFINER_VAE	ComfyUI-visible VAE filename for quality knf comfy upscale. Defaults to qwen_image_vae.safetensors; -z uses ae.safetensors when this value is not explicitly configured.
COMFY_UPSCALE_LORA	Optional quality-upscale LoRA path. Relative values resolve below COMFY_LORAS_DIR_1 when set, otherwise below $COMFY_MODELS_DIR/models/loras; the workflow receives the normalized path relative to models/loras.
COMFY_UPSCALE_LORA_TOKEN	Optional activation token prepended to quality-upscale prompt text when COMFY_UPSCALE_LORA or --lora is used.
COMFY_UPSCALE_LORA_STRENGTH	Quality-upscale LoRA model and CLIP strength. Defaults to 0.8; --lora-strength overrides it for one run.
COMFY_UPSCALE_DENOISE_BASE	Quality-upscale denoise formula base. Defaults to 0.15; --denoise-base / -d overrides it for one run while preserving automatic stage adjustments.
COMFY_PROMPT_TIMEOUT_SECONDS	Maximum seconds to wait for each queued ComfyUI prompt.
COMFY_POLL_INTERVAL_SECONDS	Seconds between ComfyUI history polling attempts.
KNF_LMSTUDIO_BASE_URL	LM Studio OpenAI-compatible API base URL. Defaults to http://127.0.0.1:1234/v1.
KNF_LMSTUDIO_MODEL	Default LM Studio model id for knf llm prompt. Required unless pass-specific model vars, CLI model options, or single-model auto-discovery provide one.
KNF_LMSTUDIO_DRAFT_MODEL	Optional model id for the first prompt-generation pass.
KNF_LMSTUDIO_REVIEW_MODEL	Optional model id for the review pass.
KNF_LMSTUDIO_API_KEY	API key passed to the OpenAI SDK. Defaults to lm-studio.
KNF_LMSTUDIO_TIMEOUT_SECONDS	Maximum seconds for LM Studio API calls. Defaults to 120.
KNF_LMSTUDIO_MODEL_AUTO	When true, auto-selects the model only if /v1/models reports exactly one model.
KNF_LMSTUDIO_CUDA_DEVICE	Explicit CUDA index for future Kneiff-managed LM Studio launch helpers.
KNF_LMSTUDIO_CUDA_DEVICE_NAME	Visible GPU name fragment, such as RTX 4070 Ti Super, resolved through nvidia-smi for future launch helpers. Existing LM Studio servers keep their current GPU.
KNF_PROMPTGEN_DRAFT_TEMPERATURE	Sampling temperature for the first prompt-generation pass. Defaults to 0.7.
KNF_PROMPTGEN_REVIEW_TEMPERATURE	Sampling temperature for the consistency review pass. Defaults to 0.2.
KNF_PROMPTGEN_MAX_TOKENS	Maximum response tokens for each prompt-generation pass. Defaults to 2048.
KNF_PROMPTGEN_REVIEW_ENABLED	Whether knf llm prompt runs the review pass. Defaults to true; --no-review disables it for one run.
KNF_PROMPTGEN_STRICT_JSON	Whether a response without one unambiguous JSON object fails instead of falling back to prompt text. A JSON object wrapped in a Markdown code fence is accepted. Defaults to true.
KNF_PROMPTGEN_SAVE_EXCHANGES	Whether to save raw prompt-generation exchanges for debugging. Defaults to false; --save-exchanges enables it for one run. Saving requires an active storage root.
KNF_PROMPTGEN_EXCHANGE_DIR	Optional override for raw exchange JSON files. Relative values resolve below the selected storage root; absolute values are used exactly. When unset, saved exchanges go to <storage>/.llm_promptgen.
KNF_WORKERS	Positive worker count for dataset export, image inspection, and SimpleTuner workspace staging in the typed AppRC storage section. Defaults to 8; set it in .env.apprc-storage, through knf config edit/config set, or in the shell.
BASE_URL	OpenAI-compatible server base URL for image captioning.
OPENAI_BASE_URL	Alias for BASE_URL.
OPENAI_API_KEY	OpenAI-compatible API key for image captioning. Local servers may accept not-needed.
API_KEY	Alias for OPENAI_API_KEY.
KNF_SIMPLETUNER_EXECUTABLE	Optional app-wide SimpleTuner console-script override for training and model conversion. Must be an existing absolute path or begin with ~; it takes precedence over PATH.
KNF_SIMPLETUNER_CUDA_DEVICE	Prepared by the LoRA launcher when --cuda-device is set.
KNF_SIMPLETUNER_FALLBACK_CUDA_DEVICE	Prepared by the LoRA launcher when --fallback-cuda-device is set.
VIRTUAL_ENV	Active virtual environment path.
PYTHONPATH	Import-path override for local smoke tests. Prefer editable installs for normal development.

knf comfy and knf llm require KNF_STORAGE or --storage. Their native AppRC sections resolve packaged defaults, app-wide overrides, storage-local .env.apprc-storage, explicit --env-file values, and process environment values according to the selected root options.

.env.apprc-storage cannot select its own storage. AppRC must resolve KNF_STORAGE before it knows which storage-local file to load. Use knf project use NAME, shell KNF_STORAGE, or root --storage to select the project.

Related: use How-To User Guides: environment problems for the first checks when imports resolve from the wrong location.

Configuration Files

Important config files:

File	Role
pyproject.toml	Python packaging, dependencies, entry points, and tool settings.
justfile	Development automation around uv, diagnostics, and locks.
~/.config/knf/knf.apprc.toml	AppRC named-storage registry written by knf config storage add or knf project init. KNF_APPRC_TOML overrides this path.
~/.config/knf/.env.apprc-app	App-wide AppRC overrides created by knf config setup or knf config app init.
.env.apprc-storage	Machine-local overrides inside a registered storage root. AppRC creates it during knf project init registration. It is loaded only after storage selection and cannot select that root.
.env	Local OpenAI-compatible caption server settings.
.git/	A main-branch repository initialized for a new project by knf project init. Its local user.name comes from --git-user-name and defaults to kneiff; no email, remote, commit, global Git setting, or Git LFS setup is created.
.gitignore	Project-root ignore rules written by knf project init, including .env.apprc-storage, .llm_promptgen/, .old_manifests/, HF/, and TRAINING/.
.gitattributes	Project-root Git LFS tracking declarations for image, model, archive, and workbook files. It does not run Git LFS setup.
default_tags.txt	Project-owned starter seed containing kneiff, the activation token, and the species token. It is not consumed by Kneiff at runtime.
vocabulary.knf.yaml	Committed strict kneifftags.vocabulary-extension schema-version-2 document containing project identities and project-only vocabulary.
prompts.knf.yaml	Optional committed version-1 project overlay for the packaged prompt catalog. It owns project-specific scenes; its rows require explicit nonempty uses lists.
workflows/showcase_<preset>.workflow.json	Optional committed project override for a packaged showcase workflow.
MANIFEST.knf.xlsx	Fixed A-H dataset workbook generated and reconciled by knf dataset sync. Every image occupies 13 rows. Column C stores independent user input; the thumbnail and five derived output cells are merged across the block.
MANIFEST.yaml	Generated strict schema-version-2 sidecar for Git diffs. It stores logical record identity and user input but no derived captions.
__kneiff_manifest__	Very-hidden workbook metadata sheet containing schema provenance, record coordinates, stable identifiers, exact content identity, and generated-value fingerprints.
configs/*.knf.yaml	Dataset export and optional training.simpletuner config. It must be a direct child of configs/; source_root, manifest_path, export_root, and allow_export_inside_source are invalid because Kneiff derives fixed project paths. knf project init always creates the Sygred Anima configs/ANIMA.knf.yaml template with local component paths and the Flux2 Klein 9B configs/F2K_9B.knf.yaml template using black-forest-labs/FLUX.2-klein-base-9B with unset component paths.
SOURCE/	Source image root scanned by knf dataset sync; manifest paths stay relative to this directory. A new project includes empty 0-FULLBODY/ and 2-HEAD/ folders. Add anatomy-focused directories only when a project config maps them.
HF/<config-id>/	Public Hugging Face dataset export root generated by knf dataset sync. The root HF/ directory exists after initialization but is ignored and initially empty.
TRAINING/<config-id>_<run>/	Ignored SimpleTuner workspace generated by knf train prepare or fresh knf train start. The root TRAINING/ directory exists after initialization but is ignored and initially empty.
TRAINING/<config-id>_<run>/kneiff-training-run.json	Required exact-schema Kneiff run-state marker with schema_version: 1, a not_started, running, incomplete, failed, or complete status, normalized absolute paths, explicit optional fields, a nonempty unique subset list, and SHA-256 hashes for every generated JSON artifact. Subsets must match direct dataset/ children from data-backend instance_data_dir values. Markerless, symlinked, modified, or stale workspaces are rejected rather than migrated. The generated simpletuner-config.json remains the executable source of truth.
.old_manifests/	Archived manifest workbooks retained by the project scaffold.
README.md	Export-root Hugging Face dataset card generated by dataset sync.
metadata.jsonl	Export-root Hugging Face ImageFolder metadata generated by dataset sync.
.hfignore	Export-root Hugging Face ignore file generated by dataset sync.
HF/<config-id>/.gitignore	Export-root Git ignore file generated by dataset sync.
.kneiff-export-state.json	Export-root local incremental sync state generated by dataset sync and ignored by generated .hfignore and .gitignore.
kneiff-training-image-grid.jpg	Export-root contact sheet generated by knf dataset sync.
TRAINING/<config-id>_<run>-kneiff-validation-progress-grid.jpg	Final validation-progress contact sheet generated after successful knf train.
src/kneiff/project_vocabulary.py	Read-only schema detection, strict extension loading, cached isolated engine composition, project identity metadata, and public definition access.
src/kneiff/project_vocabulary_migration.py	Pure schema-version-1 project vocabulary conversion, validation, diagnostics, and field-aware legacy input rewrites.
src/kneiff/datasets/manifest/block_schema.py	Authoritative 13-row workbook field order, headers, merge geometry, and dimensions.
src/kneiff/datasets/manifest/block_sync.py	Transactional content reconciliation, migration staging, archive creation, activation, and rollback.
kneifftags @ git+https://huggingface.co/spaces/kneiff/kneifftags.git@v0.4.1	Exact caption-engine source release. Kneifftools uses only symbols exported from the Kneifftags package root.
.gitignore	Local and generated files excluded from Git.
.github/workflows_inactive/	Ignored local starter CI workflows, if present.

Related: use configuration model for how local settings, environment variables, and package defaults should stay understandable.

Model Registry

kneiff.model_registry is the source of truth for SimpleTuner profile metadata, compact promotion filename IDs, known model aliases, and friendly dataset-card labels.

ID	SimpleTuner profile	Dataset-card label	Recognized aliases
ANIMA	anima / base-v1.0	Anima Base v1.0	Anima, anima-base-1.0
F2K_4B	flux2 / klein-4b	Flux.2 Klein 4B	F2K 4B, Flux.2 Klein 4B
F2K_9B	flux2 / klein-9b	Flux.2 Klein 9B	F2K 9B, Flux.2 Klein 9B
CHROMA	chroma / hd	Chroma1-HD	Chroma, Chroma1-HD
ZI	z_image / none	Z-Image	ZI, Z-Image
SDXL	sdxl / none	SDXL	SDXL, Pony

Public Interfaces

Documented public surfaces:

Surface	Current Name	Stability
Package import	kneiff	Public package root.
CLI entry point	knf	Public command declared in pyproject.toml.
JTP-3 wrapper entry point	jtp3-wrap	Public command declared in pyproject.toml.
CLI implementation module	kneiff.main	Import owner for console entry points.
AppRC application contract	kneiff.config.KNEIFF_RC	Native AppRC capability declaration with application name knf.
Typed runtime bundle	kneiff.config.KneiffConfig	Aggregate of all validated Kneiff AppRC sections.
Native config sections	kneiff.config.StorageConfig, kneiff.config.ComfyConfig, kneiff.config.LmStudioConfig, kneiff.config.PromptgenConfig	Typed AppRC config classes; construct these directly instead of using loader helpers.
Storage registry	~/.config/knf/knf.apprc.toml	AppRC-managed persistent storage list.
App-wide overrides	~/.config/knf/.env.apprc-app	App-wide AppRC dotenv layer.
Storage selector env var	KNF_STORAGE	Required selector for runtimeful commands; accepts a registered name or path.
Dataset config names	configs/*.knf.yaml	Public naming convention for path derivation.
Dataset config YAML keys	Strict documented fields	Duplicate and unknown fields are rejected before export or training artifact generation, including nested caption, augmentation, resize, caption-output, publishing, and Hugging Face fields. Mapping and caption-output subset names must be exact YAML strings without surrounding whitespace; duplicate normalized mapping sources are rejected. source_root, manifest_path, export_root, and allow_export_inside_source are rejected. The top-level training block is validated by the training schema.
Manifest workbook	MANIFEST.knf.xlsx	Public dataset workbook name.
Manifest YAML sidecar	MANIFEST.yaml	Generated diff-friendly manifest output; do not treat it as editable source.
Relative path field	Relative_path	Required first row in every 13-row image block.
Caption output config	caption_outputs	Public global sidecar config block.
Caption output overrides	caption_outputs_overrides	Public per-subset override block.
Export mirroring config	augmentations.mirrored_extra, augmentations.mirrored_transform, augmentations.seed	Public export-time mirror controls. mirrored_extra is an exact YAML boolean, and seed is an unquoted YAML integer; strings and other coercible scalars are rejected.
Image resize config	image_resize	Public export-time resize block.
Hugging Face publishing config	publishing.huggingface	Optional dataset-card fields such as repo_id, pretty_name, version, optimized_for_model, license, tags, provenance, adult_content, and notes.
Training selector	training	Kneiff-owned selector with only enabled, backend, and simpletuner. enabled requires an exact YAML boolean. backend accepts only the exact unpadded string simpletuner; other, misspelled, or whitespace-padded values are rejected. Unknown fields are rejected even when the nested SimpleTuner block is disabled.
SimpleTuner config	training.simpletuner	Public LoRA training config block. Kneiff-owned fields use strict types and reject unknown keys; nested native SimpleTuner override mappings remain pass-through. Kneiff owns the fixed workspace paths simpletuner-config.json, simpletuner-multidatabackend.json, optional simpletuner-validation-prompts.json, .simpletuner-cache/, and _simpletuner-output/. Generated-path override keys are rejected, including trainer.output_dir and trainer_testrun.output_dir.
SimpleTuner subsets	training.simpletuner.subsets	Required non-empty image-subset mapping when SimpleTuner training is enabled. Names and optional backend id values must be portable single-segment identifiers; set disabled: true to exclude a subset from the workspace copy.
SimpleTuner curriculum	training.simpletuner.curriculum	Optional single-run exact-set curriculum block. phases names active image subsets at each start_step; subsets: all expands to every configured image subset, and total steps still come from training.simpletuner.trainer.max_train_steps.
SimpleTuner validation schedule	training.simpletuner.validation_schedule.start_step	Optional strict non-negative optimizer step for Kneiff's delayed scheduled validation. A positive value runs at exactly that step and every trainer.validation_step_interval afterward; the step-0 benchmark and final validation remain unchanged. It requires a positive step interval and rejects trainer.validation_epoch_interval.
SimpleTuner testrun profile	training.simpletuner.trainer_testrun	Optional trainer-behavior overrides used only with fresh knf train prepare --testrun or knf train start --testrun; it cannot change the fixed output directory.
SimpleTuner startup validation	training.simpletuner.trainer.disable_benchmark	Native SimpleTuner flag. Set true to skip the before-training baseline render or false to run it.
SimpleTuner validation prompts	training.simpletuner.validation_prompts	Strict Kneiff-owned prompt-library config generated by kneiff.training.lora.simpletuner_validation_prompt_artifacts; the wrapper and each source reject unknown fields and require exact YAML booleans. Root styles supplies caption styles unless a source overrides them with caption_styles. It selects curated training_validation captions from the resolved project catalog, direct custom prompts, independently enabled fixed core wolf/residential-street/office-worker controls, and optional manifest samples. Controls and manifest samples each require one effective supported style (tags, chroma, or nlg). In a custom prompt, {activation_token} resolves to the selected project's character token. negative_control_species and from_manifest.profile are removed; training config cannot redirect the project prompt source.
ComfyUI byte upload	ComfyUiClient.upload_image_bytes(data, *, filename, subfolder="", overwrite=True, type="input")	Upload encoded image bytes to ComfyUI. type accepts input, output, or temp; omitting it preserves input-upload behavior.
ComfyUI owned cancellation	ComfyUiClient.cancel_owned_prompts(prompt_ids)	Delete only matching pending prompt ids and interrupt an active prompt only when the current queue confirms that its id belongs to the supplied set.
Solo T2I entrypoint	kneiff.infer.comfy.pipelines.t2i_solo.run(request, ...)	Run the Krea2 solo preset through shared staged orchestration.
Duo T2I entrypoint	kneiff.infer.comfy.pipelines.t2i_duo.run(request, ...)	Run the Anima baseline and Flux2 cleanup preset through shared staged orchestration.
T2I contracts	kneiff.infer.comfy.pipelines.T2iPipelineRequest, T2iPipelinePlan, T2iJob, T2iStageResult, T2iPipelineResult	Typed request, planning, job, stage, and final-result interfaces for direct Python callers.
Project vocabulary	kneiff.project_vocabulary.ProjectVocabulary	Loaded schema-2 extension, isolated composed Kneifftags engine, primary character/species metadata, and ordered activation tokens.
LoRA config templates	kneiff.training.lora.templates/*.yaml	Packaged config templates: complete.yaml, chroma.yaml, z-image.yaml, flux2-klein-4b.yaml, flux2-klein-9b.yaml, anima.yaml, and sdxl.yaml.

The former load_comfy_config(), load_lmstudio_config(), and load_promptgen_config() helpers are removed. Construct the native section classes or KneiffConfig instead. Non-Typer callers must run KNEIFF_RC.bootstrap(storage=...) before constructing env-backed config; the knf CliRuntime performs that bootstrap automatically.

Package areas:

Package Area	Role
kneiff.config	Native AppRC application contract, typed bundle, and config section classes.
kneiff.clients.openai_compatible	OpenAI-compatible API client setup.
kneiff.project_vocabulary	Schema detection, strict Kneifftags extension loading, project identity metadata, and isolated engine composition.
kneiff.datasets.manifest	Fixed-block schema, path discovery, workbook and sidecar IO, exact-content reconciliation, Kneifftags rendering, and transactional sync.
kneiff.datasets.export	Dataset export config loading, planning, caption-profile rendering, writing, and reporting.
kneiff.datasets.augmentations	Image augmentation transforms and batch workflow.
kneiff.model_registry	Shared compact model IDs, SimpleTuner profile metadata, public aliases, and dataset-card labels.
kneiff.training.lora	SimpleTuner config generation, launch, config templates, and checkpoint conversion.
kneiff.training.lora.config_templates	Packaged LoRA config template discovery and reading helpers.
kneiff.training.lora.simpletuner_config	Shared parsing helpers for the training.simpletuner project config block.
kneiff.training.lora.simpletuner_validation_prompt_artifacts	SimpleTuner prompt-library models and artifact builders.
kneiff.project_resources	Project vocabulary, prompt-overlay, workflow, and scaffold validation orchestration.
kneiff.prompts	Project-agnostic prompt catalog types, fixed controls, parsing, and overlay merging.
kneiff.infer	Diffusion inference package.
kneiff.infer.comfy	ComfyUI client, typed resource references, showcase generation, and server-side upscale orchestration.
kneiff.infer.lmstudio	LM Studio model resolution, dataset-shaped prompt fields, and two-pass prompt-generation orchestration.
kneiff.utils.gpu	NVIDIA GPU discovery and CUDA launch environment selection helpers.
kneiff.cli.app	Typer command tree used by the knf entry point.
kneiff.app.workbench	Gradio caption and validation-prompt workbench used by the Hugging Face Space shim.
kneiff.utils	Shared utility facade and owned utility modules.
kneiff.utils.image.caption	Generic VLM/server image captioning and sidecar helpers.
kneiff_dev	Maintainer-only tooling scaffold.

Related: use How-To User Guides: run the first command for the first user-facing smoke test.

Figure Visual Tokens

docs/render_figures.py owns the figure theme, token names, and rendered SVG assets. Keep figure captions and generated asset names stable.

Token	Value	Use
blue	#00a2ff	Maintainer and interface nodes
green	#32bc00	User tasks and editable data
orange	#f4a261	Entry points and project boundaries
purple	#8b5cf6	References and generated artifacts
teal	#00a6a6	Configuration and selection flow

Related links:

• Use static figure rules before adding docs figures.
• Use documentation authoring before changing docs structure or figure assets.