Upload DOCS.md with huggingface_hub

DOCS.md

@@ -1,22 +1,24 @@
 # voice — Help
 
-Generated from `voice --help` and `voice <cmd> --help` (v3.0.1, 12 commands).
+Generated from `voice --help` and `voice <cmd> --help` (v3.1, 14 commands).
 
 ## voice --help
 
 ```text
 usage: voice [-h] [-v] [--non-interactive] [--version]
              [--completion {bash,zsh,fish}]
-             {get,cast,delta,add,list,info,remove,cleanup,auth,report,path,doctor} ...
+             {get,cast,delta,graft,chorus,add,list,info,remove,cleanup,auth,report,path,doctor} ...
 
 Lift a model's voice and cast it onto another model.
 
 positional arguments:
-  {get,cast,delta,add,list,info,remove,cleanup,auth,report,path,doctor}
+  {get,cast,delta,graft,chorus,add,list,info,remove,cleanup,auth,report,path,doctor}
     get                 Get a voice from a model (safetensors repo, .gguf, or
                         URL)
     cast                Cast a voice onto a .gguf or .safetensors file
     delta               Make a reusable style (voice − base)
+    graft               Graft one voice onto another (DELLA single graft)
+    chorus              Blend voices: pulse + support + lead (DELLA chorus)
     add                 Add a voice from local voice.safetensors + voice.json
     list                List stored voices
     info                Show voice details
@@ -61,12 +63,6 @@ options:
   --yes        Assume yes to prompts (overwrite without asking)
 ```
 
-Names: letters, numbers, hyphens, underscores — no spaces, `/`, `\`, dots,
-colons, and never starting with `delta-` (reserved). Stored lowercased
-(`StyleTune-V2` → `styletune-v2`). When no `--name` is given, the default is
-slugified from the source (`./my model.gguf` → `my-model`); an explicit
-`--name` that breaks the rules is an error.
-
 ## voice cast
 
 ```text
@@ -97,18 +93,6 @@ options:
   -q, --quiet         Quieter: progress and success notes off (warnings and
                       errors still print)
 ```
-Philosophy: preserve quality, avoid dequant→quant cycles. Safetensors high-fidelity
-lm_head is quantized once to Q8_0 (Q4 saves little: Q8_0 1.062 vs Q4_0 0.562 B/param).
-All GGML quants supported (trivial passthrough): Q8_0/Q4_0/Q4_1/Q5_0/Q5_1/Q8_1/Q8_K/
-Q1_0/Q2_K/Q3_K/Q4_K/Q5_K/Q6_K/IQ1_S/IQ1_M/IQ2_*/IQ3_*/IQ4_NL/IQ4_XS/TQ1_0/TQ2_0/MXFP4/NVFP4
-are kept at obtained quant (never upscale Q2→Q6, no inventing data). `--quant`
-accepts any quant name; encoding uses gguf lib where implemented (Q8_0/Q4_0/F16/F32/BF16).
-Unsupported quants (e.g. Q1_0/Q8_1/Q8_K where the lib raises NotImplemented) are a
-clear error naming the quant — pass `--quant keep` to preserve the original instead.
-Generic tensors keep target quant (F32 norms stay F32, never forced Q8_0).
-`--out` refuses to write through a symlink (path or parent dir). If the target
-architecture is unknown the output is labeled `llama` (GGUF requires an arch)
-with a warning. BF16 math uses round-to-nearest-even, not truncation.
 
 ## voice delta
 
@@ -126,10 +110,66 @@ options:
                still print)
 ```
 
-Niche cases need typed confirmation: delta-as-base asks `UNDO THE UNDO`,
-delta-on-delta asks `DOUBLE DIP`, delta-minus-delta asks `BIG BRAIN`.
-Non-interactive (`--yes`/pipe) fails fast with an error instead of prompting —
-re-run on a TTY to confirm.
+## voice graft
+
+```text
+usage: voice graft [-h] [--density DENSITY] [--epsilon EPSILON]
+                   [--lambda_ LAMBDA_] [--rescale {l1,inv_p}] [--seed SEED]
+                   [--out OUT] [--yes] [-q]
+                   [pulse] [donor]
+
+positional arguments:
+  pulse                 Pulse voice name (default: pick from registry)
+  donor                 Donor voice name (default: pick from registry)
+
+options:
+  -h, --help            show this help message and exit
+  --density DENSITY     Keep-fraction for magnitude pruning (default: 0.8)
+  --epsilon EPSILON     Rank-ramp half-width (default: 0.1)
+  --lambda_ LAMBDA_     Global rescale after combine (default: 1.0)
+  --rescale {l1,inv_p}  Prune rescale: l1 (stable) or inv_p (paper-faithful)
+  --seed SEED           Bernoulli seed for reproducible grafts (default: 42)
+  --out OUT             Output voice name (default: chorus-<pulse>-<donor>)
+  --yes                 Assume yes to prompts (overwrite without asking)
+  -q, --quiet           Quieter: progress and success notes off (warnings and
+                        errors still print)
+```
+
+## voice chorus
+
+```text
+usage: voice chorus [-h] [--config] [--density DENSITY]
+                    [--lead-density LEAD_DENSITY] [--epsilon EPSILON]
+                    [--lead-epsilon LEAD_EPSILON] [--lambda_ LAMBDA_]
+                    [--rescale {l1,inv_p}] [--seed SEED] [--out OUT] [--yes]
+                    [-q]
+                    [pulse] [donors ...]
+
+positional arguments:
+  pulse                 Pulse voice name (default: pick interactively)
+  donors                Support + lead voice names (0-2; 1 = duet at lead
+                        density)
+
+options:
+  -h, --help            show this help message and exit
+  --config              Stage knob screens per graft (Enter accepts each
+                        default; screens prefill from flags)
+  --density DENSITY     First-graft density (default: 0.8)
+  --lead-density LEAD_DENSITY
+                        Lead-graft density (default: 0.9)
+  --epsilon EPSILON     Rank-ramp half-width (default: 0.1)
+  --lead-epsilon LEAD_EPSILON
+                        Lead-graft epsilon (default: 0.05; keeps 0.9±eps
+                        valid)
+  --lambda_ LAMBDA_     Global rescale after combine (default: 1.0)
+  --rescale {l1,inv_p}  Prune rescale: l1 (stable) or inv_p (paper-faithful)
+  --seed SEED           Bernoulli seed for reproducible choruses (default: 42)
+  --out OUT             Final output voice name (default:
+                        chorus-<pulse>-<lead>)
+  --yes                 Assume yes to prompts (overwrite without asking)
+  -q, --quiet           Quieter: progress and success notes off (warnings and
+                        errors still print)
+```
 
 ## voice add
 
@@ -148,10 +188,8 @@ options:
                still print)
 ```
 
-The tensor is copied and validated before `voice.json` is written, so an
-invalid source adds nothing and never leaves metadata pointing at a partial file.
-
 ## voice list
+
 ```text
 usage: voice list [-h] [--base] [-q] [base]
 
@@ -178,7 +216,9 @@ options:
   -q, --quiet  Quieter: progress and success notes off (warnings and errors
                still print)
 ```
+
 ## voice remove
+
 ```text
 usage: voice remove [-h] [--yes] [-q] voice
 
@@ -238,13 +278,6 @@ options:
                         errors still print)
 ```
 
-After local save (private `~/.voices/reports.jsonl`), shows preview:
-  Will share: voice: styletune-v2, tensor: lm_head.weight [262144,2816] BF16, target: model.gguf
-  Leave a breadcrumb to help the next person? [y/N] (N):  ← Enter = No, one try
-Non-interactive skips unless --yes. Local: outbox at `~/.voices/outbox/<id>.json`.
-Remote: `Wiself/voice-reports` `data/reports-YYYY-MM.jsonl`, batched, dedup `report_id`.
-```
-
 ## voice path
 
 ```text
@@ -266,10 +299,3 @@ options:
   -q, --quiet  Quieter: progress and success notes off (warnings and errors
                still print)
 ```
-
-## voice --version / --completion
-
-```text
-voice --version           # show version + environment
-voice --completion bash|zsh|fish   # print shell completion
-```