docs: usability pass — gotchas page, glossary, labelled waveform, less jargon

[shaypal5]

Summary

Critical re-read of the docsite from the lens of a tired DS volunteer (2 hours/week, scanning for value). Reorganises content so the first scroll surfaces what a consumer actually needs — and the operator-grade detail moves out of the way without being lost.

What changed

New pages

• docs/gotchas.md — Common mistakes. Consolidates ten previously-scattered pitfalls into one ~2-minute read: has_violence derivation rule, hardcoded speaker-dir trap, peak-is-0.79 surprise, UPPERCASE/lowercase casing, NEG-isn't-violent, split: train warning, quality_flags semantics, Google-clip flag, timestamp/pad relationship, .json vs .jsonl. Plus a clone-verification snippet.
• docs/glossary.md — One canonical place for AGG/VIC/SW/BEN, F0, SSML, IR, ISM, dBFS, RMS, prosody cap, dirty file, weak vs strong labels, voice IDs.

New visual

• docs/assets/sp_sv_a_0001_00_waveform.png — Real labelled waveform of an SV clip rendered from the corpus data + its .jsonl events. Now the lead element on the home page. Shows the typical escalation arc (VERB → DIST → PHYS) with intensity badges.

Home page

• Leads with status pill (provisional · 2026-05-12) + a 4-line load snippet + the labelled waveform.
• Tabbed product picker replaced with side-by-side team cards (rendered via extra.css grid).
• Toy-corpus warning and "What's not in this corpus" callout moved below the fold.

Schema Reference

• Rewritten as a single annotated JSON example with click-to-expand (1)! explanations.
• Fields ordered by frequency of use: top-level → weak_label → speakers → paths → quality_flags → acoustic_scene (Tier B) → preprocessing_applied → generation_metadata (collapsed) → diagnostic/reserved fields.
• Adds .txt transcript format section (previously undocumented).

Audio Format

• Leads with the three consumer facts (peak ~= 0.79, padding-in-timestamps, ≥3s) in one table.
• Two-peak-fields convention surfaced (loudness_target_peak_dbfs vs normalized_dbfs).
• Pipeline internals (M3a per-turn RMS, Stage 1/2/3 normalization, target rationale) collapsed into ??? admonitions for the curious.

Taxonomy

• Critical admonitions opened from ??? (collapsed) to !!! (visible): NEG-trap, ACOU vs DIST.
• New "How intensity and typology relate" section with per-typology expected max_intensity ranges.
• Adds disclosure: scripts are LLM-generated Hebrew dialogue, not human transcripts.

Team guides

• Reframed as the differential vs shared reference (less duplication of casing rules, schema, audio format).
• Speaker tables split into speaker_id and voice columns (no more arrow-joined cells).
• Full clip listings collapsed into ??? blocks; summary counts surfaced.
• Per-team "training-time notes" trimmed to project-specific bullets.

Deliveries

• Reordered: current state and known limitations first, diffs vs prior deliveries collapsed at the bottom.
• Status pills for visual scan.

Operator jargon stripped

• Milestone codes (M3a, M8a, M10a) removed from consumer-facing pages.
• "Wet test" / "spec validation" / "pipeline bootstrapping" replaced with plain language.
• SSML/F0/IR/ISM/Whisper/dBFS/RMS now defined on first use via Glossary cross-links.

Plumbing

• mkdocs.yml: site_name → "AVDP Synthetic Corpus", new nav entries (Start here, Common mistakes, Glossary), abbr extension, extra_css for assets/extra.css.
• docs/assets/extra.css: status pills + team-card grid (responsive, dark-mode aware).

Test plan

• mkdocs build passes with zero broken anchors / missing-link warnings
• Custom HTML (<div class=\"team-cards\">, <span class=\"status-pill\">) renders correctly through md_in_html
• Waveform PNG resolves at /assets/sp_sv_a_0001_00_waveform.png
• All gotchas link targets resolve (#1-dont-derive..., #4-uppercase-in-json..., etc.)
• Auto-deploy via existing .github/workflows/docs.yml (triggers on push to main touching docs/ or mkdocs.yml)

🤖 Generated with Claude Code

[github-actions]

pr-agent-context report:

This run includes a failing check on PR #7 in repository https://github.com/DataHackIL/avdp-synth-corpus

Diagnose and fix the failing checks below, then push all of these changes in a single commit.

# Failing Checks

## FAIL-1
Type: Commit status
Context: pre-commit.ci - pr
Status: failure
URL: https://results.pre-commit.ci/run/github/1210843386/1778619602.J6z3ALh9QDCnBBTxqrEqDg

Summary:
    checks completed with failures

Run metadata:

Tool ref: v4
Tool version: 4.0.21
Trigger: pull request opened
Workflow run: 25761916157 attempt 1
Comment timestamp: 2026-05-12T21:00:28.240975+00:00
PR head commit: e27b08d1bd24d205298aa704a435a74067252616