docs: doc-audit 20260313#3610
Merged
Merged
Conversation
[skip ci]
Change default disk cache locations from ~/.qsv/cache/... to ~/.qsv-cache/... across docs, CLI help and code (describegpt, fetch, fetchpost, .claude skill). Also normalize Redis TTL env var names in docs from QSV_REDIS_TTL_SECONDS to QSV_REDIS_TTL_SECS (and related command-specific vars), and update a few doc links/badge references (luau source path and polars badge). These edits unify cache path usage and clarify TTL env naming. [skip ci]
Contributor
There was a problem hiding this comment.
Pull request overview
Documentation audit updates across CLI help text, docs, templates, and a few in-source doc comments to reflect current defaults and references (cache directory naming, Redis env var names, embedded interpreter/version notes, and performance/memory-check docs).
Changes:
- Align cache documentation/defaults to
~/.qsv-cache/...and Redis TTL env var naming (*_TTL_SECS). - Refresh various docs/help references (Luau version/link targets, Polars badge tag, benchmark README fixes).
- Update performance/memory-check documentation and clean up outdated env var entries in
dotenv.template.
Reviewed changes
Copilot reviewed 19 out of 19 changed files in this pull request and generated 1 comment.
Show a summary per file
| File | Description |
|---|---|
| src/cmd/stats.rs | Doc comment formatting update in update_modes Safety section. |
| src/cmd/fetchpost.rs | Help text updated for default disk cache dir and Redis TTL env var name. |
| src/cmd/fetch.rs | Help text updated for default disk cache dir and Redis TTL env var name. |
| src/cmd/describegpt.rs | Help text + default disk cache dir updated to ~/.qsv-cache/describegpt. |
| scripts/README.md | Fix typos and correct docopt wordlist script path/name. |
| dotenv.template | Update Redis connstr examples to redis://...; remove obsolete MCP env var entries. |
| docs/help/luau.md | Refresh source links to master and update referenced line ranges. |
| docs/help/fetchpost.md | Align help doc to ~/.qsv-cache/... and QSV_REDIS_TTL_SECS. |
| docs/help/fetch.md | Align help doc to ~/.qsv-cache/... and QSV_REDIS_TTL_SECS. |
| docs/help/describegpt.md | Align help doc to ~/.qsv-cache/... and QSV_REDIS_TTL_SECS. |
| docs/help/TableOfContents.md | Update Luau link target and Polars badge/tag reference. |
| docs/PERFORMANCE_TLDR.md | Update example write-buffer value to match documented default. |
| docs/PERFORMANCE.md | Expand CONSERVATIVE memory-check explanation; update nightly rust info filename reference. |
| docs/INTERPRETERS.md | Update embedded Luau version reference. |
| docs/FEATURES.md | Update Magika link target. |
| docs/ENVIRONMENT_VARIABLES.md | Align high-card threshold default and expand CONSERVATIVE memory-check description. |
| README.md | Refresh Luau helper-function links and adjust logo reference link. |
| CONTRIBUTING.md | Update docopt fork link reference. |
| .claude/skills/qsv/qsv-describegpt.json | Align describegpt disk cache default path to ~/.qsv-cache/describegpt. |
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
jqnatividad
added a commit
that referenced
this pull request
Jul 11, 2026
…n (roborev #3610) The previous commit raised every KPI label uniformly into the indicator domain, which is safe for number-only tiles (empty padding below the centered number) but risks overlapping gauge tiles — the always-present Completeness gauge and any dictionary-backed measure gauge sit lower in the domain. Compute label_y per tile in both render paths: number-only tiles keep the raised position (snug under the number), gauge tiles anchor at the reserved line, fully below the indicator domain so the label can never land on the dial. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
jqnatividad
added a commit
that referenced
this pull request
Jul 11, 2026
The per-tile label split (roborev #3610) dropped gauge-tile labels to a lower line, creating an uneven, distracting baseline across the KPI row. Visual review shows the gauge dial is a semicircle in the TOP of the domain with its number below it, so the label band directly under the number is clear of the dial — the overlap #3610 guarded against does not occur at the label's actual position. Anchor every label (number-only AND gauge) at the same raised y for one clean baseline snug under the numbers, with no dial overlap. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
jqnatividad
added a commit
that referenced
this pull request
Jul 12, 2026
…e measures (#4185) * feat(describegpt): emit x-qsv.gauge_range KPI hint for canonical-scale measures Teaches the `--dictionary --infer-content-type` pass to propose a `gauge_range` [min, max] for numeric MEASURE columns on a canonical scale (percent, ratio, rating, bounded index), which `viz smart --dictionary` reads as `x-qsv.gauge_range` to draw a gauge KPI tile instead of a bare number. Follows the existing propose-then-verify discipline (same as null_values): - LlmDictField carries the raw model proposal; parse_llm_dictionary_response only shape-validates ([min,max] of two finite numbers, min<max), gated on --infer-content-type. - combine_dictionary_entries (and the two-pass baseline variant) keep it ONLY when the finalized role is `measure` AND the observed [min,max] fits inside the proposed scale — a range the data spills past is dropped (verify_gauge_range, run after role coercion). An unverified gauge is simply not emitted, so no-flag and non-measure runs stay byte-identical. - build_x_qsv emits it as the 2-element array viz consumes. `target` (delta baseline) is deliberately NOT emitted: a business goal is unfalsifiable from the data, so an LLM would fabricate one. Deferred; viz's delta path stays dormant until a hand-authored dictionary supplies a target. The refine prompt is intentionally left untouched: like role/concept, the first-pass gauge_range survives the refine overlay via baseline preservation (locked by two_pass_refine_omitting_gauge_range_preserves_the_baseline), so the DEFAULT_DICTIONARY_REFINE_PROMPT guard test stays green. Caveats: the guardrail catches scale OVERFLOW, not wrong-scale (a 0-1 ratio the model mistags [0,100] still passes containment); and whether a given LLM returns sensible ranges is not CI-testable — verify with a live QSV_VIZ_REGEN_LLM=1 run. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * fix(describegpt): scope gauge_range to renderable continuous measures (roborev #3606) Medium: viz's build_kpi_row only turns a column into a gauge KPI tile when it earned a box/violin/histogram distribution panel, which low-cardinality integer ratings never do — so the prompt's 1-to-5 / 0-to-10 rating examples advertised gauges viz cannot render. Narrowed the prompt to CONTINUOUS canonical scales (percentage, probability/ratio, bounded continuous index) and added an explicit clause telling the model NOT to gauge discrete/low-cardinality ratings. (Gauging panel-less measures in viz is left as a follow-up enhancement.) Low: verify_gauge_range now also requires the column's qsv type to be Integer/Float, so a String column the LLM mis-tags role:measure whose lexicographic min/max happen to parse as floats can no longer keep/emit a gauge. New test combine_drops_gauge_range_for_non_numeric_type; prompt-gating assertion updated to the new bullet wording. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * feat(viz): render KPI tile labels as wrapped subtitles below each indicator Long auto-generated KPI labels (e.g. "Mean Profit Margin Percentage") rendered as the plotly Indicator's built-in title — a large font above the number — and overran narrow tiles, colliding with neighbours. Move the label out of the indicator title into a smaller, word-wrapped subtitle annotation centered BELOW each tile: kpi_indicator now owns only the number/gauge/delta and reserves the bottom band of its domain, and both render paths (typed grid + inline) draw the label via kpi_label_annotation. wrap_kpi_label greedily wraps on word boundaries (never hard-splitting a word); tile width (tile count) sets the wrap threshold. Verified in-browser on the gemma-inferred sales_sample gauge dashboard: labels sit cleanly below each tile, and the longest wraps to two lines with no overlap. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * fix(viz): enlarge KPI subtitle labels (13px) below each indicator The previous KPI subtitle labels were too small (10px) to read comfortably. Keep them below the indicator (not as titles) but bump the font to 13px, widen the reserved bottom band to 30% to fit two wrapped lines, and tighten the wrap threshold so long labels still break cleanly. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * fix(viz): tighten the gap between KPI numbers and their labels The label sat at the very bottom of the reserved band, a full band below the indicator's number (which has its own bottom padding), reading as too detached. Anchor the label up inside that padding (14% of the band above the reserved line) in both render paths so it sits snug under the number. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * fix(viz): keep raised KPI label off the gauge; per-tile label position (roborev #3610) The previous commit raised every KPI label uniformly into the indicator domain, which is safe for number-only tiles (empty padding below the centered number) but risks overlapping gauge tiles — the always-present Completeness gauge and any dictionary-backed measure gauge sit lower in the domain. Compute label_y per tile in both render paths: number-only tiles keep the raised position (snug under the number), gauge tiles anchor at the reserved line, fully below the indicator domain so the label can never land on the dial. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * fix(viz): align all KPI labels on one baseline under the numbers The per-tile label split (roborev #3610) dropped gauge-tile labels to a lower line, creating an uneven, distracting baseline across the KPI row. Visual review shows the gauge dial is a semicircle in the TOP of the domain with its number below it, so the label band directly under the number is clear of the dial — the overlap #3610 guarded against does not occur at the label's actual position. Anchor every label (number-only AND gauge) at the same raised y for one clean baseline snug under the numbers, with no dial overlap. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * docs(viz,describegpt): document the KPI overview row & gauge_range/target hints The KPI overview row (Completeness gauge + headline measure tiles), and the x-qsv.gauge_range / x-qsv.target dictionary hints that turn a measure tile into a gauge or a "vs target" delta, were undocumented. Add them to the viz `smart` Overview-panels list and the --dictionary help, and note gauge_range emission under describegpt --infer-content-type (clarifying target is hand-authored, not inferred). Regenerated docs/help/{viz,describegpt}.md. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * docs(viz): reword KPI hint bullets as prose to fix bogus help-table row (roborev #3613) The nested `- "gauge_range"` / `- "target"` bullets inside the --dictionary Options help began with a dash, so the docopt-based help generator parsed them as an option definition and emitted a spurious `-, -` row in docs/help/viz.md. Reword both hints as flowing prose (no leading dashes) and regenerate the help; the --dictionary row is now a single clean entry that still documents both hints. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * feat(viz): move Completeness to the header; add KPI gauge/delta gallery example Completeness was a permanent KPI gauge tile that read ~100% for most datasets and crowded the overview row. Move it to a quiet "Completeness:" line in the dashboard header table (between Columns: and Compiled:), and drop it from the KPI row - which now leads purely with the headline MEASURES and returns None when a dataset has no measure to headline (e.g. a map-only dataset, so its map reclaims panel-0). build_kpi_row no longer needs the row count. Add a deterministic gallery example (examples/viz/sales_kpi_dict.schema.json + gen_gallery.py entry -> smart_sales_kpi.html) that showcases both dictionary KPI hints on sales_sample: x-qsv.gauge_range [0,1] draws Discount % / Profit Margin % as GAUGES, and x-qsv.target 0.25 on Profit Margin adds a "vs target" DELTA (mean 0.21 -> red -0.042). Hand-authored, so it regenerates without a live LLM. Regenerated the gallery (39 figures) and the affected smart dashboards (their completeness now shows in the header). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * fix(viz): force-add the gallery KPI dictionary fixture (gitignored *.json) sales_kpi_dict.schema.json is referenced by gen_gallery.py and drives the committed smart_sales_kpi.html, but .gitignore's `*.json` rule dropped it from the previous commit. Force-add it (matching the sibling *_dict.schema.json fixtures) so the gallery example is reproducible. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * docs(viz): sync KPI-row help text with header-completeness change (roborev #3615) The viz smart help still described the KPI row as leading every dashboard with a built-in Completeness gauge, but completeness now lives in the header metadata table and the KPI row is omitted when a dataset has no headline measure. Reword the "KPI overview row" bullet accordingly and regenerate docs/help/viz.md. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
No description provided.