SESSION: domus-nvim README + JSON Terminal Training

Summary

Two-part session in domus-nvim repo, then domus-captures. First: README.adoc rewritten — installation instructions, prerequisite packages per distro, language toolchains (Rust, Python, Node.js). Second: yq and gron training modules created in domus-captures following the existing jq training pattern (sessions + drills + runnable bash scripts). Also added a jq live-data guide using gh api instead of synthetic test data.

Agent: Claude Opus 4.6 via Claude Code CLI

Part 1: domus-nvim README Overhaul

Problem

README.adoc had no installation instructions. A user cloning the repo wouldn’t know:

  • How to back up existing Neovim config (4 directories)

  • That a Nerd Font, C compiler, and make are required (not listed)

  • What happens on first launch (~90 plugins install, Mason downloads tooling)

  • How to uninstall

Changes

  • Reordered sections: Features first, then Prerequisites, then Installation

  • Expanded prerequisites table: added C compiler, make, Nerd Font (required); fd, lazygit, tmux (optional)

  • Added per-distro install commands (Arch, Ubuntu/Debian, macOS)

  • Added language toolchain section: Rust via rustup, Python/ipython, Node.js

  • New Installation section: backup, clone, first launch expectations, uninstall

Commits (domus-nvim)

  • 712df16 — docs: Add installation instructions, expand prerequisites

  • e91098f — docs: Add package installation instructions per distro and language toolchains

Part 2: Notes API Discussion

Discussed options for interacting with notes via APIs. Determined the user’s workflow (terminal + git + browser for Antora) already has an API via gh CLI and filesystem. Identified jq, yq, gron as the skill investment — query your own data in JSON from the terminal.

Bug Fixes

  • zsh: no matches found on gh api — ? is a glob character in zsh; must quote URLs

  • repo: null in search output — GitHub API uses full_name (snake_case), not fullName

Part 3: yq + gron Training Modules

Created in domus-captures

Module Sessions Drills Scripts

yq

5 (basics → infrastructure)

5

6 (runner + 5)

gron

3 (basics → composition)

3

4 (runner + 3)

jq (guide)

—

—

1 (live-data guide)

yq Session Topics

  1. YAML basics, output formats, .key, .[], -o=json bridge

  2. select, has, path, keys, collect

  3. In-place edit (-i), merge (*), delete (del), add (+=)

  4. Multi-document YAML, di, anchors/aliases, explode, split

  5. Infrastructure: antora.yml comparison, GitHub Actions, docker-compose

gron Session Topics

  1. Flatten JSON, grep paths, ungron round-trip, discovery workflow

  2. API discovery: gh api + gron exploration, field name discovery

  3. Composition: gron + jq + yq multi-tool pipelines

jq Live Data Guide

Exercises using gh api with real repos instead of synthetic test files. Cross-repo commit activity, file tree analysis, code search, AsciiDoc header extraction via awk→jq pipeline.

Commit (domus-captures)

  • bcfa290 — feat(training): Add yq + gron training modules, jq live-data guide (30 files, 3,615 lines)

Part 4: Commands Saved

Git cross-repo audit commands added to partials/worklog/quick-commands.adoc:

  • Cross-repo daily commit audit (for/loop across all domus repos)

  • Git log as JSON + jq aggregation

  • gh api code search with correct full_name field

  • Cross-repo activity dashboard

  • Antora attribute comparison via yq

Teaching Points

  • zsh glob expansion — ?, *, [ are glob characters. Quote URLs: gh api 'url?param=val'

  • GitHub API field names — always snake_case (full_name, stargazers_count)

  • -s (slurp) — jq -s collects lines of JSON objects into an array; without it each line is separate

  • Tool decision: gron for discovery (don’t know the shape), jq for extraction (know the path), yq for YAML→JSON bridge

  • -o=json — the most important yq flag; converts YAML output to JSON for jq piping