Skip to content

docs: replace fabricated command output with real output, add a guard #77

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
copyleftdev merged 2 commits into from
Jul 30, 2026
+233 −146
Merged

docs: replace fabricated command output with real output, add a guard #77

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
51e03db
docs: replace fabricated command output with real output, add a guard
copyleftdev Jul 30, 2026
827829b
fix(tests): return an error rather than panic in the docs guard
copyleftdev Jul 30, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
57 changes: 9 additions & 48 deletions docs/src/cmd-anomalies.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -131,61 +131,22 @@ vajra anomalies claims_batch.ndjson --format json

```json
{
"records_analyzed": 1247,
"anomaly_count": 8,
"type_instabilities": [],
"numeric_outliers": [
{
"path": "$.claims[*].service_lines[*].charge_amount",
"record": 834,
"value": 47250.0,
"z_mad": 6.3,
"median": 285.0,
"mad": 195.0
},
{
"path": "$.claims[*].service_lines[*].charge_amount",
"record": 1102,
"value": 0.01,
"z_mad": -4.8,
"median": 285.0,
"mad": 195.0
}
],
"rarity_outliers": [
{
"path": "$.claims[*].status",
"record": 419,
"value": "voided",
"self_information_bits": 10.3,
"frequency": 1,
"total": 1247
}
],
"structural_deviations": [
{
"record": 662,
"jaccard_distance": 0.31,
"missing_paths": [
"$.claims[*].subscriber.group_number",
"$.claims[*].subscriber.member_id",
"$.claims[*].provider.npi",
"$.claims[*].provider.taxonomy"
],
"extra_paths": []
"path": "$[*].score",
"value": 22.1,
"z_mad": 13.040333333333344,
"median": 10.5,
"mad": 0.5999999999999996
}
],
"type_instability": [
{
"path": "$.claims[*].service_lines[*].quantity",
"records": [88, 204, 917],
"expected_type": "number",
"actual_type": "string",
"instability": 0.002
}
]
"rare_values": []
}
```

Three arrays, always present even when empty. `z_mad` is the modified z-score — deviation from the median in MAD units — so it is robust to the outliers it is detecting.

---

## Example: With --explain
Expand Down
29 changes: 15 additions & 14 deletions docs/src/cmd-cascade.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -104,25 +104,26 @@ vajra cascade commits.ndjson \

```json
{
"records": 1247,
"entities": 34,
"trigger_events": 312,
"response_events": 89,
"cascade_rate": 0.285,
"self_fix_rate": 0.742,
"hot_entities": [
{"entity": "alice", "cascades": 23, "fraction": 0.258},
{"entity": "bob", "cascades": 14, "fraction": 0.157},
{"entity": "charlie", "cascades": 9, "fraction": 0.101}
"cascade_rate": 0.3333333333333333,
"total_events": 3,
"total_cascades": 1,
"self_fix_rate": 0.0,
"cascades": [
{
"entity": "a.rs",
"trigger": { "author": "", "time": "2025-01-01", "value": "feat: add" },
"response": { "author": "", "time": "2025-01-02", "value": "fix: repair" },
"same_author": false
}
],
"chains": [
{"trigger": "bug", "response": "fix", "count": 62, "median_delta_days": 2.3},
{"trigger": "bug", "response": "revert", "count": 18, "median_delta_days": 0.4},
{"trigger": "regression", "response": "fix", "count": 9, "median_delta_days": 4.1}
"hot_entities": [
{ "entity": "a.rs", "total": 2, "cascades": 1, "cascade_ratio": 0.5 }
]
}
```

`self_fix_rate` is the share of cascades where trigger and response share an author. A low rate means someone else is cleaning up.

---

## When to Use It
Expand Down
57 changes: 17 additions & 40 deletions docs/src/cmd-essence.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -142,50 +142,27 @@ vajra essence claim.json --profile ai --format json --budget 500

```json
{
"vajra_essence": {
"version": "0.1.0",
"profile": "ai",
"input_hash": "b3a7f2c1d4e5...",
"structure": {
"root_type": "object",
"total_nodes": 847,
"distinct_paths": 23,
"max_depth": 6
},
"dominant_motif": {
"path": "$.claims[0].service_lines[*]",
"count": 14,
"shape_hash": "f2c1d4e5...",
"fields": ["procedure_code", "service_date", "charge_amount", "allowed_amount", "status", "adjustment"]
},
"anomalies": [
{
"path": "$.claims[0].service_lines[2,7,11].allowed_amount",
"type": "missing",
"severity": 4.2
},
{
"path": "$.claims[0].diagnosis[1]",
"type": "structural_deviation",
"severity": 3.1
}
],
"notable": [
{
"path": "$.claims[0].service_lines[*].adjustment.reason_code",
"observation": "value 'CO-45' in 8/14 instances (57%)"
}
],
"meta": {
"budget_tokens": 500,
"truncated": false,
"observations_included": 4,
"observations_total": 7
"identity": "document(nodes=25, paths=9, depth=3)",
"structure": [],
"anomalies": [
{
"path": "$[*].score",
"description": "numeric outlier (value=22.1, z_mad=13.04)",
"score": 0.22499999999999998,
"anomaly_strength": 1.0,
"concern_relevance": 0.5,
"entropy_signal": 0.0,
"instability": 0.0,
"rarity": 0.0,
"structural_coverage": 0.0
}
}
],
"observations": []
}
```

Each entry carries its scoring components alongside the final `score`, so a ranking is decomposable — `--explain` prints the same weights in text form. The active profile's weight vector determines how the components combine.

@coderabbitai coderabbitai Bot Jul 30, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win

Remove the obsolete meta.truncated guidance.

The updated output no longer contains meta, but the following paragraph still directs users to meta.truncated. Update or remove that truncation claim to match the new schema.

🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/src/cmd-essence.md` at line 164, Update the documentation around the
ranking output description to remove the obsolete meta.truncated guidance and
any claim that relies on the removed meta field. Ensure the text reflects the
current schema, which exposes scoring components and score without a meta
object.


The AI profile collapses aggressively. Motifs are represented once with counts. Observations are sorted by score-per-token. The `meta.truncated` field tells the downstream model whether anything was cut.

---
Expand Down
3 changes: 3 additions & 0 deletions docs/src/cmd-inspect.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -158,6 +158,9 @@ vajra inspect claim.json --format json
}
```

`structural_findings` also appears when a domain plugin recognises the document's shape — a package manifest declaring an install-time hook, for example. It is omitted entirely when empty, so its absence means "nothing recognised", not "not checked". See [Domain Plugins](./plugins.md#structural-detectors).


---

## When to Use It
Expand Down
19 changes: 9 additions & 10 deletions docs/src/cmd-query.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -138,16 +138,15 @@ vajra query claim.json 'entropy($.claims[*].status)' --format json
```

```json
{
"function": "entropy",
"path": "$.claims[*].status",
"result": {
"shannon_entropy": 1.22,
"normalized_entropy": 0.77,
"cardinality": 3,
"support": ["adjudicated", "pending", "denied"]
}
}
1.584962500721156
```

`query` emits the bare result, not an envelope. An analysis function returns a number; a path expression returns the selected value or array. That makes it directly composable:

```bash
if (( $(echo "$(vajra query data.json 'entropy($[*].author)') < 3" | bc -l) )); then
echo "contributor diversity below threshold"
fi
Comment on lines +146 to +149

@coderabbitai coderabbitai Bot Jul 30, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win

Request JSON output before passing the result to bc.

Line 147 uses the default text format, so bc receives the human-readable report instead of a numeric scalar.

Proposed fix 
-if (( $(echo "$(vajra query data.json 'entropy($[*].author)') < 3" | bc -l) )); then
+if (( $(echo "$(vajra query data.json 'entropy($[*].author)' --format json) < 3" | bc -l) )); then
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
```bash
if (( $(echo "$(vajra query data.json 'entropy($[*].author)') < 3" | bc -l) )); then
echo "contributor diversity below threshold"
fi
🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/src/cmd-query.md` around lines 146 - 149, Update the vajra query
invocation in the contributor-diversity threshold example to request JSON output
before piping its numeric result to bc, while preserving the existing entropy
expression and comparison logic.

```

---
Expand Down
56 changes: 22 additions & 34 deletions docs/src/cmd-stats.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -180,52 +180,40 @@ vajra stats claim.json --format json

```json
{
"document": "claim.json",
"total_nodes": 847,
"distinct_paths": 23,
"paths": {
"$.claims[*].service_lines[*].charge_amount": {
"count": 14,
"cardinality": 12,
"entropy": 3.41,
"normalized_entropy": 0.88,
"types": {"number": 14},
"null_rate": 0.0,
"absent_rate": 0.0,
"paths": [
{
"path": "$[*].id",
"entropy": 1.584962500721156,
"normalized_entropy": 1.0,
"cardinality": 3,
"total_count": 3,
"max_rarity": 1.5849625007211563,
"numeric": {
"min": 45.0,
"max": 1250.0,
"mean": 312.5,
"median": 285.0,
"mad": 195.0,
"percentiles": {
"p01": 45.0, "p05": 52.0, "p25": 125.0,
"p50": 285.0, "p75": 425.0, "p95": 890.0, "p99": 1125.0
}
"min": 1.0, "max": 3.0, "mean": 2.0, "median": 2.0, "mad": 1.0,
"p05": 1.1, "p25": 1.5, "p75": 2.5, "p95": 2.9
},
"top_values": [
{"value": "285.00", "count": 2},
{"value": "125.00", "count": 2}
{ "value": "1", "count": 1 }
]
},
"$.claims[*].service_lines[*].status": {
"count": 14,
{
"path": "$[*].name",
"entropy": 1.584962500721156,
"normalized_entropy": 1.0,
"cardinality": 3,
"entropy": 1.22,
"normalized_entropy": 0.77,
"types": {"string": 14},
"null_rate": 0.0,
"absent_rate": 0.0,
"total_count": 3,
"max_rarity": 1.5849625007211563,
"numeric": null,
"top_values": [
{"value": "adjudicated", "count": 10},
{"value": "pending", "count": 3},
{"value": "denied", "count": 1}
{ "value": "a", "count": 1 }
]
}
}
]
}
```

Output is a single `paths` array, one entry per distinct wildcard path. `numeric` is `null` for non-numeric paths. With `--window`, the response instead carries `windows` and `trends`.

---

## When to Use It
Expand Down
Loading
Loading