@vextlabs/theron-cli 0.2.1 → 0.4.0

package/skills/ticket-triage.md

@@ -0,0 +1,200 @@
+---
+name: ticket-triage
+description: Reproduce, severity-assess, and resolve theron-cli support tickets end-to-end; escalate only when root cause requires dev/founder intervention or the customer is Enterprise.
+allowed-tools: Read, Write, Bash
+---
+
+# TICKET TRIAGE PLAYBOOK
+
+## ═══ HARD RULES ═══
+
+1. **Acknowledge the stated problem in one sentence** — reflect back the customer's exact words before doing anything else.
+2. **Reproduce before advising** — run the failing command or trace the failing code path yourself. Gut-feel fixes are a liability.
+3. **Never promise a fix you have not verified** — say "I can likely fix this by…" only if you have tested it; say "I will confirm" if unverified.
+4. **Severity is not urgency** — a cascading race condition in `repl.ts` (Critical) may take longer to fix than a banner color regression (Low). Separate the two.
+5. **Escalate by impact, not by "is hard"** — if you can fix it in one file without side effects, fix it. Escalate only when root cause touches the SDK contract, alignment layers, model-serving, or billing.
+6. **Document what you tried and why it failed** — "I checked `src/auth.ts:127`, found the cached token has no TTL check, ruled out the API endpoint because it returns 401 not 403" gives the next person reasoning, not a mystery.
+7. **Never commit a workaround to `src/`** — temporary patches in production source become permanent debt. Fix the root cause or escalate.
+
+## ═══ PHASE A: INTAKE & TRIAGE ═══
+
+**A1. Extract the one-line problem**
+- Read the ticket title and first message verbatim.
+- Restate it: "So you're seeing [symptom] when you run [command] on [OS/version]?"
+- Do not editorialize or assume missing details.
+
+**A2. Gather CLI-specific context**
+Run or ask the customer to run:
+```bash
+theron --version          # CLI version (packages/theron-cli/package.json)
+node --version            # Node version — CLI requires ≥18
+cat ~/.theron/config.json # Active profile + API endpoint
+theron auth status        # Token validity (src/auth.ts)
+```
+Also collect:
+- OS + shell (darwin zsh / linux bash / win32 pwsh)
+- When did it start? (Today? After `npm upgrade theron-cli`? After a deploy to Vercel?)
+- How many users affected? (Just them? Their org? All Enterprise customers on the same endpoint?)
+- What is the customer trying to accomplish? (Blocking a release? Annoying UX? Nice-to-have?)
+
+**A3. Assign severity + impact**
+- **Critical**: Blocks all work (auth broken, CLI won't start, `src/index.ts` crashes on launch, data loss, checkout unreachable). Escalate immediately.
+- **High**: Blocks a feature class (all tool calls fail, REPL loop hangs, all verifier checks return false, receipt signing fails). Fix today or escalate.
+- **Medium**: Affects a specific workflow with a workaround (one tool in `src/tools/` errors, one verifier in `src/verifiers/` false-positives, profile switching fails, banner renders wrong). Fix this week.
+- **Low**: Cosmetic or rare edge case (typo in output, one endpoint returns wrong status code on malformed input, `update_check.ts` shows stale version). Fix when convenient.
+
+**A4. Check if this is known**
+```bash
+git log --oneline packages/theron-cli | head -50
+grep -r "TODO\|FIXME\|HACK" packages/theron-cli/src/
+```
+- If already reported → link the commit/issue, summarize the fix status, give ETA.
+- If a duplicate → thank them, link the canonical issue, close with a one-liner.
+
+## ═══ PHASE B: REPRODUCE & CONFIRM ═══
+
+**B1. Match symptom to the CLI's known failure taxonomy**
+
+Before doing anything open-ended, check which category applies:
+
+| Symptom | First place to look |
+|---|---|
+| `theron: command not found` after install | `packages/theron-cli/src/index.ts` entry point; check `package.json` bin field |
+| Auth error / 401 / token loop | `src/auth.ts` — token cache TTL, refresh logic, `~/.theron/config.json` |
+| REPL hangs or crashes mid-session | `src/repl.ts` — streaming loop, `src/streaming.ts` — chunk parsing |
+| Tool call returns wrong output or silently fails | `src/tools/` — match the tool name to its file (`bash.ts`, `glob.ts`, `grep.ts`, `ls.ts`, `stoa.ts`) |
+| Verifier fires falsely or is silently skipped | `src/verifiers/` — `lint.ts`, `source_gate.ts`, `test_smoke.ts`, `types.ts` |
+| Profile switch doesn't take effect | `src/profiles/index.ts`, `src/profile_match.ts` |
+| Receipt missing or malformed | `src/receipt.ts`, `src/stoa.ts` |
+| Banner displays wrong or crashes startup | `src/banner.ts` |
+| `theron ship` fails | `src/ship.ts` — Vercel env injection, `scripts/bring_up_theron.sh` path |
+| SDK tool-contract mismatch (tool schema drift) | `packages/theron-agent-sdk/src/tools/local-contract.ts`; never re-inline TOOL_SCHEMAS in CLI |
+
+**B2. Run the minimal reproduction**
+- Follow the exact steps the customer reported in their environment version.
+- Capture the full output — never truncate stack traces.
+- Record git status, env vars (mask secrets), and `~/.theron/config.json` state.
+- If intermittent: run 5+ times, note failure rate, check for race in `src/streaming.ts` or `src/sessions.ts`.
+- If unreproducible: tell the customer exactly what you ran, why it should trigger the bug, and ask for their `~/.theron/` config (redacted).
+
+**B3. Narrow the root cause**
+- Is it CLI, SDK (`packages/theron-agent-sdk/`), backend API (`marketing/api/`), third-party (OpenRouter, RunPod, Stripe), or user error?
+- Trace from entry point (`src/index.ts`) through the relevant command handler to where it breaks.
+- Compare against `main` branch: `git diff main packages/theron-cli/src/`.
+- If root cause is in the agent-SDK contract (tool schemas, loop interface, MCP adapter): escalate — do not patch CLI around it.
+- If you cannot reproduce after 30 minutes of honest effort → escalate with your exact reproduction steps and all data collected.
+
+## ═══ PHASE C: FIX & VERIFY ═══
+
+**C1. State the root cause in one line**
+Example: "The token cached in `src/auth.ts:127` has no TTL check; it passes a stale token to every API call after 24h without refreshing."
+
+Always cite: file path + line range + mechanism.
+
+**C2. Design the minimal fix**
+- Smallest change that fixes the root cause without side effects.
+- If the fix touches `src/auth.ts`, `src/repl.ts`, or `src/streaming.ts` → check that profile switching, session resumption, and receipt signing still work.
+- If the fix touches `src/tools/index.ts` or `src/verifiers/index.ts` → run the full verifier suite against a real session.
+- If the fix requires changing the tool contract in `packages/theron-agent-sdk/src/tools/local-contract.ts` → escalate; a contract change breaks VS Code, the backend loop, and all consumers simultaneously.
+- If the fix is in model weights, LoRA, async job queue, or `marketing/api/` → escalate to dev.
+
+**C3. Test the fix**
+```bash
+# Run existing tests
+cd packages/theron-cli && npm test
+
+# Run the exact command that failed
+theron [failing-command] [flags]
+
+# If auth-related: force a token expiry and re-run
+rm ~/.theron/config.json && theron auth login && theron [failing-command]
+
+# If verifier-related: run against the specific verifier
+# (check src/verifiers/types.ts for the interface; run directly if it has a test harness)
+```
+- Confirm the reproduction case passes.
+- Confirm no new test failures.
+- If you touched rendering (`src/render.ts`, `src/banner.ts`) → visually inspect the terminal output.
+
+**C4. End-to-end verification**
+- Close the REPL completely, restart from `theron` cold start, re-run the failing scenario.
+- Confirm the problem is gone, not masked (e.g., don't verify by running a different command).
+- If the bug corrupted session state in `~/.theron/` → prepare the exact `rm` / migration steps for the customer.
+- If the bug affected a STOA receipt (`src/receipt.ts`) → confirm the receipt re-generates and the WebCrypto verifier at `itstheron.com` accepts it.
+
+## ═══ PHASE D: COMMUNICATE & CLOSE ═══
+
+**D1. Write the resolution message using this template**
+
+```
+## Reproduced
+[Exactly what you ran, what you saw, which file/line fails — one paragraph.]
+
+## Root Cause
+[One sentence in plain English. Cite file + line range.]
+
+## Fix
+[Numbered steps. Include file paths and the changed code if small (< 10 lines).]
+
+## Verification
+[Exact command the customer can run. Expected output verbatim.]
+
+## Status
+[ ] Merged to main (theron-cli vX.Y.Z)
+[ ] On branch fix/ticket-NNN — run `npm install -g theron-cli@next` to test early
+[ ] Escalated to [dev / founder / product]: [reason in one sentence]
+
+## Next Steps
+[What the customer must do, if anything. Otherwise: "You're all set — close and reopen if it recurs."]
+```
+
+**D2. Expectation-setting**
+- If the customer must upgrade: "Please run `npm install -g theron-cli@X.Y.Z` (or `brew upgrade theron-cli`)."
+- If there is a workaround while they wait: state it explicitly and confirm it works.
+- If `~/.theron/` data was affected: provide the exact repair commands.
+- If it touches alignment logic, receipts, or `claims.yaml`: "This touches [system]; I am flagging it for founder review before shipping. ETA: [day]."
+
+**D3. Escalation handoff**
+- **To dev**: Attach reproduction script (runnable `bash` or `ts-node`), full logs, your diagnosis with file+line, and the reason you stopped.
+- **To founder**: Only for regressions in auth/checkout/alignment layers, `claims.yaml` drift ("we claimed X, CLI does Y"), receipt integrity failures, security issues (token bypass, data leak), or Enterprise/press customers.
+- **To product**: If the fix requires a decision (breaking change to a flag? deprecate a CLI command? change pricing or plan-gate logic?). Summarize the tradeoff in ≤3 sentences.
+
+**D4. Close the ticket**
+- Do not close until the customer confirms the fix works in their environment, or you have verified it on `main` + they have the upgrade.
+- Leave one follow-up: "I will close this on [date] if we don't hear back. Feel free to reopen anytime."
+
+## ═══ ESCALATION CRITERIA ═══
+
+**Escalate to dev immediately if:**
+- Root cause is in the agent loop, orchestrator, or MCP integration (`marketing/api/_lib/`).
+- The fix requires coordinated changes across theron-cli, theron-agent-sdk, and the backend (multi-repo landing).
+- It touches the SDK tool contract in `packages/theron-agent-sdk/src/tools/local-contract.ts`.
+- It requires a database migration against Neon.
+- The bug is intermittent or unreproducible after 30 minutes of honest effort.
+
+**Escalate to founder if:**
+- Regression in a Critical system: auth, checkout, alignment-layer precedence (`src/profiles/`), receipt signing.
+- `claims.yaml` drift: the product behavior contradicts a public claim.
+- The fix changes how receipts are generated or how the WebCrypto verifier interprets them.
+- Security: token bypass, data leak, unauthorized access to session/profile data.
+- Customer is Enterprise or press.
+
+**Do not escalate if:**
+- You can fix it in one file without touching the SDK contract.
+- It is user error (malformed input, misread docs, wrong Node version).
+- It is already in the backlog with a confirmed ETA — link them there and close.
+
+## ═══ ANTI-PATTERNS (CLI-SPECIFIC) ═══
+
+- **"Try clearing your cache and reinstalling."** — If you have not reproduced it yourself, you are guessing. Reproduce first.
+- **"Upgrade to the latest version."** — If the latest `theron-cli` has the same bug, you just wasted their time. Check `CHANGELOG.md` before recommending an upgrade.
+- **Patching around an SDK contract drift in `src/index.ts`** — If the CLI is working around a broken tool schema from `theron-agent-sdk`, that is escalation territory, not a CLI patch.
+- **Closing after you push to main** — The ticket is closed when the customer verifies in their environment, not when you merge.
+- **Adding an env-var shim to hide a bug** — e.g., `SKIP_TTL_CHECK=true`. That is a workaround in disguise. Fix the root cause.
+- **"This is by design."** — If the design is wrong, fix it or escalate. Never gaslight.
+
+---
+
+## KEY PRINCIPLE
+
+**Reproducibility + honesty > speed.** A ticket is resolved when the customer verifies the fix in their own environment, not when you push code. The fastest resolution is the one you have actually tested — not the one that sounds right. Escalate early if you hit a wall; mystery handoffs are noise that costs the next person an hour.

package/skills/tolerance-analysis.md

@@ -0,0 +1,149 @@
+---
+name: tolerance-analysis
+description: Full tolerance stack-up and GD&T analysis workflow — identify the critical dimension chain, run worst-case and RSS/statistical analysis, allocate tolerances to part cost tiers, design the datum scheme, and flag the binding contributor; invoke whenever a mechanical assembly has a gap, interference, clearance, or fit requirement that must be verified before release or when geometric controls (flatness, position, runout, profile) are being defined or reviewed.
+allowed-tools: Read, Bash, Write
+---
+
+═══ HARD RULES ═══
+
+1. NEVER state a tolerance figure, Cpk threshold, or sigma level as correct without tracing it to a stated requirement or a customer-supplied spec — fabricating process capability numbers is a release risk.
+2. WORST-CASE analysis is mandatory first. RSS is a supplement, not a replacement. If the worst-case gap goes negative, RSS does not save you — stop and redesign.
+3. Every dimension in the stack must map to a real physical interface: a machined surface, a bearing seat, a pressed-in pin, a weld joint, a fastener-hole center. Phantom dimensions (added for convenience) corrupt the chain.
+4. Datum reference frames (DRFs) must be functionally motivated — datums chosen to minimize gage variation, not to make drawing layout convenient. Always state which functional surface the datum controls.
+5. Call out the binding contributor explicitly by name, nominal, and tolerance — never bury it in the sum.
+6. If a tolerance requires a process that conflicts with stated material, heat-treat, or surface-finish constraints, flag the conflict rather than silently tightening the number.
+7. All bilateral tolerances must be confirmed symmetric unless asymmetric is explicitly justified (e.g., shrink fit, press fit, one-sided thermal growth).
+8. Bonus tolerance (MMC/LMC modifiers on GD&T callouts) must be computed at the actual mating envelope, not at MMC alone — show the calculation.
+9. RSS is only valid when contributors are statistically independent. Dimensions produced in a common setup, on the same fixture, or from the same bar-pull are correlated — treat them as worst-case contributors or use Monte Carlo with the correct covariance. Applying RSS to correlated contributors underestimates defect risk.
+10. For press-fit and shrink-fit interfaces: a clearance/interference stack-up answer is necessary but not sufficient — the interface must also pass a yield/stress check (Lame thick-wall equations or thin-ring approximation as appropriate) before the nominal interference is fixed.
+
+═══ PHASE A — REQUIREMENT CAPTURE ═══
+
+A1. State the assembly-level functional requirement in measurable form: minimum clearance (e.g., "gap ≥ 0.10 mm under all conditions"), maximum interference, maximum runout at a bearing journal, or positional accuracy of a dowel-pin pattern. One number, one direction.
+
+A2. Identify operating conditions that shift nominals:
+    - Thermal expansion: ΔL = α · L · ΔT per component material. For a bimetallic interface (e.g., aluminum housing, steel shaft), the differential expansion ΔΔL = (α_housing − α_shaft) · L · ΔT is a signed stack contributor — add it explicitly, do not fold into safety margin.
+    - Pre-load deflection: bearing pre-load or fastener clamp load deflects mating surfaces; compute via beam or Hertzian contact as appropriate and add to the chain.
+    - Press-fit relaxation: interference joints relax under cyclic load and temperature cycling; apply a retention factor from your material/surface-finish data or flag as unknown.
+    - Wear allowance: if service life introduces a known wear depth at a sliding interface, add it as a one-sided contributor with sign that closes the functional gap.
+
+A3. Confirm the assembly sequence and direction of measurement. A tolerance chain is one-dimensional — if the functional requirement is truly 2D or 3D, decompose into orthogonal 1D chains and solve each separately.
+
+A4. For interference fits (press or shrink): specify the target interference range [I_min, I_max], the mating materials and their yield strengths, and the bore/shaft ratio (c = D_outer / D_bore for thick-wall check). These bound the allowable tolerance allocation in Phase E before any stack math begins.
+
+═══ PHASE B — DIMENSION CHAIN CONSTRUCTION ═══
+
+B1. Trace the closed-loop dimension chain: starting from one side of the functional gap, walk through every part dimension and assembly shift that adds or subtracts until you return to the other side of the gap. Write the chain as:
+
+    GAP = Σ(closing dimensions, sign per direction)
+
+B2. Label each link: part name, feature name, nominal value, tolerance (bilateral ±t_i or GD&T control), and manufacturing process. Tabulate.
+
+B3. Assign signs (+ or −) consistently. A dimension that increases the gap is positive; one that closes it is negative. Verify the chain closes: Σ(nominals) = nominal gap.
+
+B4. Identify any GD&T geometric errors that contribute to the stack: position tolerance zones project onto the stack axis by a geometric factor (often sinθ or cosθ for angled features) — compute the projected component, do not add the full tolerance zone diameter blindly.
+
+B5. For fastener patterns — use the correct formula for the fastener condition:
+
+    Floating fastener (clearance holes both parts, fastener free to shift):
+        T_pos (each part) = (H_hole_min − D_fastener_max) / 2
+        This splits the hole-to-fastener clearance equally between the two parts at MMC.
+
+    Fixed fastener (fastener threaded or pressed into one part, clearance hole in the mating part):
+        T_pos_total = H_clearance_min − D_fastener_max
+        Allocate T_pos_total between the threaded-feature true position and the clearance-hole true position per cost or process priority — they must sum to T_pos_total, not each equal it.
+
+    Confirm the derived T_pos is achievable with the target process before proceeding; if not, increase the hole diameter or reduce the fastener size and re-derive.
+
+═══ PHASE C — WORST-CASE ANALYSIS ═══
+
+C1. Worst-case gap (minimum):
+    GAP_min = Nominal_gap − Σ|t_i|
+
+C2. Worst-case gap (maximum):
+    GAP_max = Nominal_gap + Σ|t_i|
+
+C3. If GAP_min < required minimum clearance (or > required maximum interference): the design fails worst-case. Do not proceed to RSS. Return to Phase E for allocation redesign.
+
+C4. If GAP_min passes: compute the worst-case margin = GAP_min − required_minimum. Note this margin — it is the budget available for process variation, wear, and thermal effects.
+
+═══ PHASE D — STATISTICAL (RSS) ANALYSIS ═══
+
+D1. RSS prerequisites — all three must hold, or use Monte Carlo instead:
+    (a) Contributors are statistically independent (no common setup, fixture, or material batch).
+    (b) Each contributor is normally distributed or boundable by a known distribution.
+    (c) Sufficient contributors for CLT: ≥ 4 independent links is a practical floor; fewer than 4 or highly non-normal distributions require Monte Carlo (sample ≥ 100 000 iterations, report P5/P95 and tail probability directly).
+
+D2. Compute the RSS total variation:
+    t_RSS = √(Σ t_i²)
+
+D3. Estimated gap distribution at ±3σ (assuming tolerances = ±3σ process limits):
+    GAP_mean = Nominal_gap
+    GAP_3σ = GAP_mean ± t_RSS
+
+D4. Probability of non-conformance: if t_RSS defines 3σ and GAP_min > 0 with margin m, the Z-score is m / (t_RSS / 3). Lookup or compute the tail probability — state it explicitly (e.g., "estimated non-conforming rate: 0.27% at 3σ").
+
+D5. If process capability data (Cpk) exists for any contributor, replace ±t_i with ±(3 · σ_process_actual) in the RSS sum — this gives a more accurate estimate than assuming tolerance = ±3σ.
+
+D6. State RSS result alongside worst-case result; never present RSS alone as the pass/fail verdict.
+
+D7. Monte Carlo path: when contributors are non-normal (e.g., injection-molded features with skewed shrinkage distributions, positional errors with bimodal fixture seating) or when fewer than 4 links exist, draw from the measured or estimated distributions, sum the chain, and report the simulated P0.135 (equivalent 3σ tail) or the customer-specified percentile. State the assumed distributions and their sources.
+
+═══ PHASE E — TOLERANCE ALLOCATION ═══
+
+E1. Rank contributors by their fractional share of the worst-case stack: binding contributor = highest |t_i| / Σ|t_i|. Name it and its process.
+
+E2. For each contributor, classify the process tier and its natural tolerance capability (reference ranges — always validate against the specific supplier's stated Cpk for the actual feature and feature size):
+
+    Turning/milling (standard):                ±0.05–0.10 mm
+    Turning/milling (precision, carbide, CBN): ±0.013–0.025 mm
+    Cylindrical grinding:                      ±0.005–0.013 mm
+    Surface grinding:                          ±0.005–0.025 mm
+    Honing (bore finishing):                   ±0.001–0.005 mm
+    Lapping / superfinishing:                  ±0.001–0.003 mm
+    Wire EDM:                                  ±0.003–0.010 mm
+    Sinker EDM (complex pockets, slots):       ±0.005–0.015 mm
+    Sheet metal punch/form:                    ±0.10–0.25 mm
+    Fine blanking:                             ±0.013–0.050 mm
+    Injection molding (thermoplastic):         ±0.05–0.20 mm (material- and feature-size-dependent; shrinkage anisotropy in fiber-filled grades adds directional bias — request material-specific shrinkage data from molder)
+    Die casting (aluminum/zinc):               ±0.10–0.30 mm
+    Investment casting (net-near forms):       ±0.10–0.25 mm (machining allowance still required on critical interfaces)
+    Metal additive (DMLS/SLM, as-built):      ±0.10–0.25 mm (significant surface waviness; plan post-machining on mating features)
+    Weldment, post-weld as-welded:            ±0.5–2.0 mm (straighten or machine after welding for anything tighter)
+
+E3. Apply the equal-contribution starting allocation: assign each contributor a trial tolerance of t_i = GAP_budget / N, then tighten those on inexpensive-to-control features and relax those on expensive ones, re-checking the stack sum each iteration. This is the cost-optimized allocation loop.
+
+E4. Use GD&T MMC/LMC bonus tolerance to recover tolerance budget where fit allows: a pin at MMC with position tolerance adds bonus equal to the departure from MMC — compute the bonus at the worst mating condition and credit it in the stack.
+
+E5. For interference fits: after allocating shaft and bore tolerances, verify the resulting [I_min, I_max] against the stress check from Phase A4:
+    - Minimum interference I_min must produce sufficient retention force (friction joint) or thermal seating force (shrink fit).
+    - Maximum interference I_max must not exceed the elastic limit at the bore ID (Lame hoop stress ≤ 0.67 · Sy for ductile materials as a conservative design rule; confirm with FEA for thin-walled or asymmetric hubs).
+    If the stress check fails at I_max, tighten the upper tolerance on the shaft OD (not the bore, which is typically harder to hold).
+
+E6. Document the final allocation table: part | feature | nominal | tolerance | process | unit cost impact (high/medium/low) | Cpk target.
+
+═══ PHASE F — DATUM SCHEME AND DRAWING CALLOUT ═══
+
+F1. Select the primary datum (Datum A) as the surface that controls the most critical functional direction — typically the mating face or the bore axis. It must be the surface that actually seats in assembly, not the most convenient surface to hold in a fixture.
+
+F2. Secondary (B) and tertiary (C) datums constrain the remaining degrees of freedom in the DRF. Confirm the datum precedence eliminates all 6 DOF without over-constraining. For cylindrical parts: primary = axis (2 DOF translational), secondary = face (1 DOF translational + 2 DOF rotational), no tertiary needed unless clocking matters.
+
+F3. For castings, weldments, and large sheetmetal assemblies where surface form error is large: use datum targets (points, lines, or areas per ASME Y14.5-2018 §4.24) rather than full datum planes. Datum targets replicate the actual fixture contact; full-plane datums on a warped casting introduce unstable rock. State the target locations and their coordinates in the DRF.
+
+F4. Write each GD&T callout per ASME Y14.5-2018 (or ISO 1101 — state which standard governs): feature control frame = [geometric characteristic | tolerance value | material modifier | datum references in precedence order].
+
+F5. Position tolerances on hole patterns: state diameter tolerance zone (⌀ prefix), not ± bilateral, unless the direction-specific tolerance is intentionally anisotropic (then use profile of a surface).
+
+F6. For critical interfaces (bearing bores, sealing surfaces, mating pilots): add surface finish (Ra or Rz) callout alongside the geometric control — the finish is a functional requirement, not cosmetic. For dynamic seals: Ra ≤ 0.8 µm on the shaft OD is a typical elastomeric lip-seal requirement; confirm against seal manufacturer's specification.
+
+═══ PHASE G — BINDING CONTRIBUTOR REPORT ═══
+
+G1. State the binding contributor: the single dimension whose tolerance, if cut in half, produces the largest improvement in GAP_min. Show the delta: "Tightening [Part X / Feature Y] from ±0.08 to ±0.04 improves GAP_min by 0.04 mm, recovering 40% of the current deficit."
+
+G2. State the process implication: what manufacturing operation, inspection method, or supplier tier change is required to achieve the tightened tolerance, and the estimated unit cost impact.
+
+G3. If the binding contributor is a purchased part or raw-material form tolerance (e.g., bar stock straightness, sheet flatness, casting datum-surface flatness): state whether the current supplier specification covers it, and whether incoming inspection or 100% sorting is required.
+
+G4. Deliver a final one-line verdict: "Stack PASSES worst-case with GAP_min = X mm (requirement ≥ Y mm). Binding contributor: [name], ±Z mm. RSS non-conforming rate: W% at stated process sigmas." Or: "Stack FAILS worst-case. Redesign required before RSS is relevant."
+
+KEY PRINCIPLE: Worst-case closes the loop — RSS refines the risk; the binding contributor is the only lever worth pulling first; and independent RSS applied to correlated setups is the most common error that ships defects.

package/skills/training-program.md

@@ -0,0 +1,151 @@
+---
+name: training-program
+description: Design a periodized, goal-specific resistance/conditioning training program: screen for contraindications, set phase structure, prescribe sets×reps×intensity (RPE/%1RM)+rest+tempo, supply technique cues+regressions, enforce deload weeks, and close with a mandatory physician disclaimer — invoke when a user requests a workout plan, training block, strength/hypertrophy/conditioning program, or progressive-overload schedule.
+allowed-tools: Read, Write
+---
+
+═══ HARD RULES ═══
+
+1. NEVER fabricate research figures, named study results, or injury-rate statistics as though they are ground truth. State ranges from established practice; label estimates as estimates.
+2. NEVER skip the readiness screen. A program written before you know the trainee's health status and training age is a liability, not a service.
+3. NEVER remove the physician disclaimer from any output, regardless of how the user frames their request.
+4. NEVER prescribe loads as absolute kg/lb without first knowing the trainee's actual capacity. Use RPE or %1RM with the explicit note that the trainee must determine 1RM safely via submaximal estimation, not an untested max single.
+5. NEVER omit at least one full rest day per 7-day training week.
+6. NEVER program more than 3 consecutive hard (RPE ≥8) sessions without a recovery day or deload trigger.
+7. ALL injury flags, chronic conditions, or post-surgical history → escalate immediately to "consult a qualified medical professional before proceeding" and halt program output for the flagged domain.
+8. Periodization model must match the stated goal. Mismatch (e.g., pure hypertrophy block for a powerlifting meet in 4 weeks) must be flagged and corrected with explicit rationale.
+9. Regressions must be provided for every primary lift. A program without regressions assumes perfect technique — an assumption no responsible coach makes.
+10. This is EDUCATIONAL output. The agent is not a licensed professional. Every output closes with the mandatory disclaimer block verbatim.
+11. Volume landmarks (MV/MEV/MAV/MRV) apply to TRAINED individuals (≥6 months consistent training). For untrained/novice trainees, effective stimulus begins at 5–8 sets per group per week — do NOT apply intermediate volume prescriptions to beginners; doing so is a primary driver of early dropout and overuse injury.
+12. Nutrition context is a programming variable for body-composition goals. Flag severe energy restriction (<1,200 kcal/day estimated) as incompatible with meaningful muscle retention and as a medical risk warranting physician referral. You cannot responsibly prescribe body-composition training without noting the energy availability constraint.
+
+═══ PHASE A — READINESS SCREEN ═══
+
+A1. Collect the following before writing a single set:
+    - Primary goal: strength | hypertrophy | power | fat-loss with muscle retention | endurance base | general fitness
+    - Training age: untrained (<6 mo) | novice (6–18 mo) | intermediate (1.5–4 yr) | advanced (4+ yr)
+    - Current weekly training frequency, modalities, and approximate weekly volume (sets per session × days)
+    - Available equipment (barbell+rack | dumbbells | cables | machines | bodyweight | combination)
+    - Session time budget (minutes)
+    - Injury history, chronic conditions, current pain — RED FLAGS: active injury, recent surgery (<12 mo for musculoskeletal), unmanaged cardiovascular or metabolic disease, pregnancy → halt and escalate per Hard Rule 7
+    - Mobility and movement limitations that would restrict primary patterns (e.g., wrist pain restricting front rack, hip impingement limiting squat depth, shoulder pathology limiting overhead work)
+    - Competition date if sport-specific
+
+A2. If any input is missing and material to program design, ask before proceeding. Assumptions made must be stated explicitly at the top of the program output, labeled "ASSUMED — confirm or correct before training."
+
+A3. Assign a starting tier based on training age:
+    - Untrained/novice → linear progression (LP) model: same movement patterns 2–3×/week, add load every session or every week
+    - Intermediate → undulating periodization (DUP or WUP): vary rep ranges within the week or across the week
+    - Advanced → block periodization or conjugate, matched to sport demand and competition calendar
+
+A4. If the trainee does not know their working loads, provide this starting-load protocol — do NOT send them to a 1RM test on day one:
+    "Select a load you can lift for 15 clean reps with 3–4 reps clearly remaining. That is your Day 1 working weight. Over sessions 1–3, allow loads to climb naturally at RPE 6–7 to establish your baseline. Only after 3–4 sessions of consistent execution should you attempt to estimate a 1RM via submaximal formula (e.g., load × reps × 0.0333 + load)."
+
+═══ PHASE B — PERIODIZATION ARCHITECTURE ═══
+
+B1. Define the macrocycle length relative to the goal:
+    - Fat-loss + retention: 8–12 weeks (practical deficit-tolerance window before metabolic adaptation warrants a diet break)
+    - Hypertrophy: 8–16 weeks accumulation, 1-week deload every 4–6 weeks
+    - Strength peak: 12–20 weeks; final 2 weeks = taper (volume –40–60%, intensity maintained or +5%)
+    - General fitness: rolling 4-week mesocycles with goal reassessment at each block boundary
+
+B2. Structure mesocycles explicitly. Name each and state its primary adaptation target:
+    - Anatomical Adaptation (AA): weeks 1–3 for untrained/novice; high rep (15–20), low load (RPE 5–6), technique priority over load
+    - Accumulation: volume is the primary driver; RPE ceiling 7–8; load increases are secondary to set/rep accumulation
+    - Intensification: load increases, volume decreases; RPE ceiling 8–9; maintain movement quality — drop load if form breaks before hitting RPE target
+    - Realization/Peak: competition or test week; volume low, intensity high, frequency reduced by 1 session
+    - Deload: mandatory after each mesocycle; same movement patterns, volume –40–50%, intensity –10–20%; this is not optional rest — maintaining movement patterns during deload preserves motor patterns
+
+B3. Weekly volume landmarks per muscle group — these ranges are for TRAINED individuals (Hard Rule 11):
+    - Maintenance volume (MV): ~10 sets/week per group (sufficient to avoid detraining; appropriate for a deload or life-stress week)
+    - Minimum effective volume (MEV): 10–12 sets/week (lowest volume that produces adaptation in a trained individual)
+    - Maximum adaptive volume (MAV): 12–20 sets/week (individual variation is high; start at MEV+2 sets and climb)
+    - Maximum recoverable volume (MRV): highly individual; first signs are performance plateau across 2+ sessions combined with persistent joint ache and elevated resting HR — this is not a target, it is a ceiling to avoid
+    - For untrained/novice: begin at 5–8 sets/week per muscle group; this is sufficient for robust adaptation and far below MRV; do not apply intermediate volume landmarks to beginners
+
+B4. For body-composition goals, state the energy availability constraint explicitly:
+    "Training stimulus for muscle retention requires adequate protein (1.6–2.2 g/kg body weight is the established range from sports nutrition literature) and sufficient total energy to support training. A caloric deficit deeper than ~500 kcal/day materially increases the risk of muscle loss alongside fat. This program cannot override an energy deficit; consult a registered dietitian for body-composition nutrition if needed."
+
+═══ PHASE C — SESSION DESIGN AND PRESCRIPTION ═══
+
+C1. Select a training split matched to frequency and recovery capacity:
+    - 2–3 days/week: full-body (highest per-muscle-group frequency; superior for novice stimulus)
+    - 3–4 days/week: upper/lower or push/pull/legs (PPL)
+    - 4–5 days/week: PPL or body-part emphasis split — only appropriate for intermediate/advanced with documented MRV above full-body coverage
+    - Never fill every day; rest day placement is a training variable, not wasted time
+
+C2. For every exercise prescribed, output EXACTLY this table row format:
+    Exercise | Sets×Reps | Intensity | Rest | Tempo | Regression
+    Example: Barbell Back Squat | 4×5 | 80% 1RM / RPE 8 | 3–4 min | 32X1 | Goblet Squat → Box Squat
+
+C3. Tempo notation (always 4-digit): eccentric–pause bottom–concentric–pause top. "X" = explosive/maximal intent.
+    - Strength: 31X1 (controlled descent, explosive concentric, brief reset at top)
+    - Hypertrophy: 3010 or 4010 (extended time under tension; no bounce at bottom)
+    - Power: X0X0 (maximal intent both directions; load selection must allow this — reduce load before sacrificing intent)
+
+C4. Intensity prescription logic:
+    - Novice: RPE 6–7 for first 2 weeks, RPE 7–8 thereafter; technique development is the priority adaptation, not limit strength
+    - Intermediate: %1RM as primary guide with RPE as daily autoregulation override; on a poor-readiness day, match the RPE target, not the load number
+    - Advanced: RPE-driven within prescribed %1RM bands; daily readiness adjustments expected and appropriate
+    - If trainee has no established 1RM, prescribe RPE only and use the A4 starting-load protocol — never send an untested trainee to a max effort on day one
+
+C5. Rest periods by adaptation target:
+    - Strength (1–5 reps, >85% 1RM): 3–5 minutes — incomplete rest at this intensity is not a training variable, it is a performance tax
+    - Hypertrophy (6–15 reps): 90 seconds–3 minutes; shorter rest increases metabolic stress but reduces load capacity; match to trainee's priority
+    - Muscular endurance (15+ reps): 30–90 seconds
+    - Supersets/antagonist pairs: rest after the pair, not between exercises within the pair
+
+C6. Technique cues — supply 2–3 per primary compound lift, biomechanically specific:
+    Squat: "Brace 360° around the spine before unracking — not just forward flexion of the abs; create intra-abdominal pressure as if bracing for a punch. Screw feet into the floor to generate external rotation torque through the hips. Keep ribs stacked over pelvis on the descent — rib flare is a loss of tension, not a breathing cue."
+    Deadlift: "Push the floor away; do not think 'pull the bar up.' Engage lats before initiating — attempt to put your shoulder blades in your back pockets; this protects the lumbar and keeps the bar close. Hips and shoulders must rise at the same rate off the floor: early hip rise converts a deadlift into a stiff-leg row."
+    Bench Press: "Retract and depress scapulae into the bench before unracking and hold them there for the entire set — this is your shoulder's safety structure. The bar path is not vertical: it descends toward the lower chest at roughly 45–75° and returns toward the face on the press. Do not press straight up."
+    Overhead Press: "Squeeze glutes and brace hard before initiating — the press is a full-body lift, not a shoulder exercise. Think 'punch the ceiling,' not 'push the bar.' Elbows at 45–60° from the torso at the bottom position; elbows flared to 90° externally rotates the humeral head into impingement risk."
+    Row: "Pull the elbow, not the hand — the hand is a hook; the scapula initiates the pull before the elbow bends. Avoid shrugging at the top; the goal is scapular retraction and depression, not elevation. A row that ends in a shrug is a partial rep."
+
+C7. Regressions per primary lift (required, per Hard Rule 9):
+    Barbell Back Squat → Goblet Squat (load and pattern) → Bodyweight Box Squat (depth control) → Wall Squat (hip/ankle mobility drill)
+    Barbell Deadlift → Trap Bar Deadlift (more vertical torso) → Romanian Deadlift → DB Romanian Deadlift → Hip Hinge to Wall (motor pattern)
+    Barbell Bench Press → DB Bench Press (independent arm loading) → Push-Up (elevate hands to box/bench if needed) → Band-Resisted Push-Up
+    Barbell Overhead Press → DB Seated Shoulder Press → Landmine Press (reduces lumbar demand) → Band Pull-Apart superset (shoulder health prerequisite)
+    Barbell Row → DB Single-Arm Row → Cable Seated Row → Band-Resisted Row → Scapular Wall Slide (if row mechanics are absent)
+
+═══ PHASE D — RECOVERY AND AUTOREGULATION ═══
+
+D1. Minimum 1 full rest day per 7-day week — no exceptions (Hard Rule 5). For 5-day programs, schedule 2 rest days; never program more than 3 consecutive training days without a recovery day.
+
+D2. Sleep is a programming variable, not lifestyle advice. Flag inadequate sleep (<7 hours per night chronically) as a direct program risk with specific consequences: suppressed testosterone and IGF-1 reduce anabolic signaling; elevated cortisol increases protein catabolism; impaired motor learning reduces technique acquisition rate; CNS fatigue accumulates faster, raising RPE artificially. When sleep is under 6 hours chronically, reduce training volume by ~20% rather than pushing through, because the recovery half of the adaptation equation is absent. If a trainee reports consistent sleep under 6 hours, prioritize sleep hygiene intervention before adding training volume.
+
+D3. Deload triggers — use whichever arrives first:
+    - Scheduled: every 4–6 weeks regardless of subjective feel (training debt accumulates before it is felt)
+    - Performance: RPE for a given load rises 1.5+ points above baseline for 2 consecutive sessions on the same exercise
+    - Subjective cluster (2 of 3): resting HR elevated >5–7 bpm above baseline | persistent joint ache that is present before the warm-up, not during | motivational crash or dread of training sessions
+    - Deload execution: same movement patterns and frequency, volume –40–50%, intensity –10–20%; deload is not a rest week — movement maintains motor patterns and facilitates active recovery
+
+D4. Autoregulation instruction: if the prescribed RPE cannot be achieved at the planned load, reduce load to match the RPE target — do NOT push through to hit the load number. RPE is the prescription; load is the dial that adjusts to meet it. A session where you hit the correct RPE at a lower load is a successful session, not a failed one.
+
+D5. Daily readiness check — instruct the trainee to assess three things before each session:
+    - Joint readiness: any unusual ache or stiffness in the joints loaded today? If yes → begin with the regression for affected movements, do not progress to working sets until movement feels clean
+    - Energy/CNS readiness: subjective rating 1–10; below 5 → reduce planned volume by 1–2 sets per exercise and cap RPE one point below prescription
+    - Previous session recovery: did the primary movers feel recovered vs. the last session? If no → add one additional warm-up set and reassess before working sets
+
+═══ PHASE E — PROGRAM OUTPUT FORMAT ═══
+
+E1. Open every program output with a STATED ASSUMPTIONS block listing every inference made from incomplete input, labeled explicitly: "ASSUMED — confirm or correct before training." Do not bury assumptions in prose.
+
+E2. Present the full mesocycle map before any session detail: week numbers, phase name, primary adaptation target, volume landmark (sets/group), intensity range (RPE or %1RM range), and scheduled deload weeks.
+
+E3. Session detail uses the table format from C2 for every exercise. Do not write sets/reps as prose — the table is the prescription.
+
+E4. Flag any exercise the trainee listed as uncomfortable or contraindicated with a bold CONTRAINDICATED label and provide only the regression path, not the primary lift.
+
+E5. Provide a concrete weekly progression rule for each primary lift — not a generic template. State the exact increment:
+    "Add [X kg/lb] to the bar / advance to the next RPE increment when you complete ALL sets at the prescribed RPE with 1 rep clearly remaining (1 RIR) across 2 consecutive sessions. If you cannot complete all sets at the prescribed RPE for 2 consecutive sessions, hold load and address technique before adding weight."
+    Typical increments: 2.5 kg (5 lb) for upper-body pressing/pulling; 5 kg (10 lb) for squat and deadlift patterns; halve these for novice trainees once rate of adaptation slows in weeks 4–6.
+
+E6. Close every single output with the mandatory disclaimer block below — verbatim, no shortening, no paraphrasing:
+
+---
+EDUCATIONAL DISCLAIMER: This program is provided for informational and educational purposes only. It does not constitute medical advice, diagnosis, or treatment. Training carries inherent physical risk. Before beginning any new exercise program, especially if you have any pre-existing health conditions, recent injuries, cardiovascular risk factors, or are pregnant or postpartum, consult a qualified physician or licensed healthcare provider. If you experience chest pain, dizziness, shortness of breath, joint pain, or any unusual symptom during exercise, stop immediately and seek medical attention. The agent producing this output is not a licensed strength and conditioning coach, physical therapist, or medical professional. Results vary; no outcome is guaranteed.
+---
+
+KEY PRINCIPLE: Progressive overload is the mechanism; recovery is when adaptation actually occurs; adequate energy availability is what fuels both. A program that prescribes training without accounting for sleep and nutrition is a plan to accumulate fatigue, not fitness — prescribe all three or acknowledge which constraints you are working within.

package/skills/translate.md

@@ -0,0 +1,64 @@
+---
+name: translate
+description: Translate text/documents between human languages preserving meaning, register, tone, markup, and placeholders — localizing idioms/units/dates, flagging untranslatables with alternatives, and marking low-confidence renderings for review; never silently drop or invent content.
+allowed-tools: Read, Write
+---
+
+═══ HARD RULES ═══
+
+- **Never silently drop content.** Every sentence, heading, footnote, caption, and metadata value in the source must have a corresponding rendering in the target — or an explicit OMITTED: note explaining why.
+- **Never invent content.** Do not add explanatory glosses, clarifying parentheticals, or extra sentences that have no anchor in the source. If context is missing, flag it, do not fill it.
+- **Preserve all markup and placeholders verbatim.** HTML tags, Markdown syntax, `{variable}` tokens, `%s`/`%d` printf slots, ICU message patterns, XML attributes, YAML keys — copy them character-for-character. Translate only the human-readable string segments around them.
+- **Register must match, not drift.** A formal legal clause stays formal. A casual marketing headline stays casual. Never upgrade or downgrade register without explicit instruction.
+- **Flag, never guess silently.** Any rendering below 90 % confidence must be marked `[REVIEW: <reason>]` inline. Any phrase with no adequate target-language equivalent must be flagged with exactly two alternatives and the tradeoff (see Phase C).
+- **One pass per phase.** Do not collapse phases. A mistranslation caught in Phase A costs one line; caught post-delivery it costs a retranslation and broken trust.
+- **Source of truth is the source text.** If the source is ambiguous, preserve the ambiguity and note it — do not resolve it unilaterally.
+- **Do not localize proper nouns, brand names, or technical identifiers** unless the client brief explicitly lists approved target-language equivalents.
+
+═══ PHASE A — INTAKE & TRIAGE ═══
+
+1. **Read the full source document** before translating a single word. Identify: language pair (source → target), domain (legal, medical, marketing, technical, literary, UX, etc.), intended audience, and formality register.
+2. **Catalogue every non-translatable element:** markup tags, placeholders, variable tokens, code blocks, URLs, proper nouns, brand names, units of measure, date formats, phone formats, currency symbols. List them in a triage note so Phase B can treat them consistently.
+3. **Identify the register markers** in the source: vocabulary level (Latinate vs. vernacular), sentence length, punctuation style, use of contractions, second-person pronoun choice (e.g., tu/vous in French, du/Sie in German, tú/usted in Spanish). Record the target-language equivalents you will use consistently throughout.
+4. **Flag domain-specific terminology** you will need to render consistently: legal terms of art, medical nomenclature, product/feature names, regulatory labels. Where a standard target-language term of art exists (e.g., ISO standard term, official regulatory body label), prefer it over a literal translation.
+5. **Note locale conventions** for the target language: date format (DD/MM/YYYY vs. MM/DD/YYYY vs. ISO 8601), decimal/thousands separators, measurement system (metric vs. imperial), currency placement, time format (12 h vs. 24 h), quotation mark style, and list punctuation. These will be applied in Phase B.
+
+═══ PHASE B — TRANSLATE (segment by segment) ═══
+
+6. **Translate in document order**, segment by segment (sentence or logical unit), never paragraph-lumping. This keeps every source segment traceable to its rendered output.
+7. **Markup and placeholder pass-through:** when a segment contains `{name}`, `<strong>`, `<!-- comment -->`, `%1$s`, or any structural token, copy that token verbatim into the rendered segment at the grammatically correct position for the target language. Do not translate, rename, or reorder them.
+8. **Idiom handling:** for each idiomatic expression, first determine whether a target-language idiom covers the same pragmatic function (preferred). If not, use a descriptive paraphrase that preserves the tone. Never carry the source-language idiom over literally if it would read as nonsense or produce a different connotation.
+9. **Localize units, dates, and numbers** according to the locale conventions catalogued in Phase A. Convert Imperial to metric (or vice versa) when the target locale standard differs, rounding to the same precision as the source. Spell out the conversion in a `[LOCALIZED: 5 miles → 8 km]` annotation the first time any unit class appears, then apply silently thereafter.
+10. **Tone and voice calibration:** after every three to five segments, re-read the last rendered paragraph aloud (mentally) in the target language and ask: does this sound like a native speaker in this register writing for this audience, or does it sound like translated text? Signs of translationese: calqued word order, overlong noun stacks, repeated sentence-opening patterns copied from the source, literal rendering of source-language connectives. Revise before proceeding.
+11. **Untranslatable phrases — required protocol:** when no equivalent exists, do not skip and do not invent. Insert:
+    ```
+    [UNTRANSLATABLE: "<source phrase>"
+      ALT-1: "<option>" — tradeoff: <what is gained / lost>
+      ALT-2: "<option>" — tradeoff: <what is gained / lost>
+    ]
+    ```
+    Present both alternatives to the requester before finalizing.
+12. **Low-confidence renderings:** any segment where you are uncertain about register fit, domain term correctness, or pragmatic equivalence, append `[REVIEW: <specific reason, e.g., "legal term of art — confirm with counsel"]` immediately after the segment, on the same line.
+13. **Cultural references:** for a reference (film title, proverb, celebrity name, historical event) that is well known in the source culture but opaque in the target culture, choose the most natural of: (a) established target-language equivalent if one exists, (b) transliteration + brief contextual gloss in parentheses, (c) functional equivalent that carries the same cultural weight. Flag with `[CULTURAL ADAPTATION: <original> → <choice>]`.
+
+═══ PHASE C — CONSISTENCY & GLOSSARY AUDIT ═══
+
+14. **Build an inline term glossary** as you translate: every time a domain term, proper noun, or brand name appears for the first time, record it as `source term → rendered term` in a `## Glossary` section appended to your output. Every subsequent occurrence must match the first rendering exactly.
+15. **Search your own output** for the ten most frequent content words and verify each is rendered consistently throughout. Variation in terminology (e.g., "account" rendered as both "compte" and "dossier" in French) is a glossary error — unify before delivery.
+16. **Pronoun and formality consistency check:** confirm the second-person pronoun register (formal/informal) is uniform across the entire document. A single drift (one informal "du" in an otherwise formal German document) breaks trust with native readers.
+17. **Punctuation and typography normalization:** apply target-language punctuation conventions — French guillemets « », German „lower-upper" quotes, Spanish inverted ¡ ¿ openers, em-dash vs. en-dash norms, non-breaking spaces before colons in French. These are not stylistic preferences; they are correctness requirements for the locale.
+
+═══ PHASE D — BACK-TRANSLATE SPOT CHECK ═══
+
+18. **Select 10 % of segments** (or minimum 5, whichever is greater), prioritizing: segments containing idioms, segments marked `[REVIEW]`, segments with localized units, and the opening and closing paragraphs.
+19. **Back-translate each selected segment to the source language** (mentally or explicitly). If the back-translation diverges from the source in meaning — not in wording, but in meaning — revise the target rendering. Wording variation is acceptable; semantic shift is not.
+20. **Re-read the entire output as a standalone document** (not alongside the source). Ask: does this read as a native-authored document in the target language, or does the structure reveal its translated origin? Fix any remaining translationese.
+
+═══ PHASE E — DELIVERY PACKAGE ═══
+
+21. **Produce the final translated document** with all `[LOCALIZED]` annotations on first use, all `[CULTURAL ADAPTATION]` annotations, and all `[REVIEW]` flags preserved inline so the requester knows exactly where human expert judgment is still needed.
+22. **Produce the Glossary section** (`## Glossary`) listing every source → target term pair used.
+23. **Produce a Flagged Items summary** (`## Flagged Items`) listing, by segment reference or paragraph number: every `[UNTRANSLATABLE]` block with both alternatives, every `[REVIEW]` item with the specific reason, and every `[CULTURAL ADAPTATION]` with the rationale for the choice made.
+24. **State explicitly what was NOT done:** if any section was intentionally left in the source language (e.g., legal boilerplate the client retains in English), name it and confirm it was deliberate, not an omission.
+
+KEY PRINCIPLE: The translator's obligation is complete semantic fidelity to the source — preserving what was said, how it was said, and for whom it was said — while producing a document that reads as if it were written natively in the target language; any gap between those two goals must be surfaced to the requester, never resolved silently.