README: document usage accounting, and fix two 404 links

[YuyangXueEd]

You asked whether the README should cover the new configuration. It should — but the gap is bigger than research_projects.

The README only ever described the TUI. collect, report and validate were not mentioned once. Someone landing on the front page had no way to discover that usage accounting exists, which also means the ownership labels looked like an unexplained requirement. Documenting research_projects alone would have been a leaf on a tree with no trunk.

Added

A Usage Accounting section covering:

• the three subcommands and what each is for
• the owner / project / purpose label contract, including why project is the research project and not the group code — with the mri_recon vs mri-recon trap called out
• the config file, its keys, and the discovery order (--config → $KUBMONITOR_CONFIG → ~/.config/kubmonitor/project.yaml)
• the research_projects spelling check, with its real output, and the fact that it is advisory and that validate still works with no config

Plus links to docs/LABELS.md and examples/project.yaml, which nothing pointed at before, and the warning to keep members.yaml out of public repos.

Fixed: two links that 404

https://github.com/vios-s/kubmonitor-cli   -> HTTP 404    (hyphen)
https://github.com/vios-s/kubmonitor_cli   -> HTTP 200    (underscore)

The source-install git clone and the Build Status badge both used the hyphen. So the documented way to install from source could not have worked for anyone.

-v is now listed next to -V as well.

Verified rather than written from memory

• subcommand flags taken from --help output
• discovery order read from find_default_config
• every documented config key checked to be one kmconfig.py actually parses
• the worked example is real output, run and diffed against the text
• all five relative links resolve
• heading levels checked — my first draft nested "Keyboard Shortcuts" under the accounting section, which belongs to the TUI walkthrough

Docs only; no code changes.

🤖 Generated with Claude Code

[Copilot]

🟡 Changes recommended

Unresolved documentation findings must be addressed before approval.

Get a fresh assessment by requesting another Copilot review.

Pull request overview

This documentation-only PR expands the README with usage-accounting guidance and fixes broken repository links.

Changes:

• Documents commands, labels, configuration, validation, and supporting resources.
• Fixes source-install and build-status URLs.
• Documents the -v version flag.
• Six unresolved nit findings remain regarding documentation accuracy and completeness.

File summaries

File	Summary
README.md	Adds usage-accounting documentation and corrects installation/status/version references.

Review details

Suppressed comments (3)

README.md:132

• purpose is not required by the validator: missing owner/project labels are errors, while missing purpose only adds a warning and still returns success. Calling all three labels required contradicts the implemented contract.

| `kubmonitor validate` | Check job YAML carries the required ownership labels — *before* you deploy it. |

README.md:183

• This repeats the unsupported claim that spelling drift splits a project across every report. report.py does not group on research_project, so the immediate effect is only two distinct stored values, not two report rows.

With `research_projects` set, `validate` flags a name that looks like a
misspelling of a registered one — the failure mode that quietly splits one
project across two rows in every report:

README.md:165

• label_prefix in this project config is not consumed by kubmonitor validate --config; validation still defaults to unprefixed labels and requires the separate --prefix option. With a non-empty value here, the command shown below will report missing labels, so clarify this distinction or update the validator.

label_prefix: ""                       # optional: prefix on the three labels

• Files reviewed: 1/1 changed files
• Comments generated: 3
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.