docs

You are running /docs in the current working directory's repo. Goal: author the three top-of-repo documentation files — README.md, CLAUDE.md, mkdocs.yml — or, where they exist, refresh them in place.

Argument (optional): $ARGUMENTS — readme, claude, or mkdocs for just that file; all (or empty) for all three.

Refresh, don't clobber. Existing prose, tables, and section order are authoritative. You may only: replace the generated badge block, add missing standard sections, and correct stale facts (wrong owner/repo, dead workflow name, changed template version). Never delete a hand-written section to standardise it — report it instead. Prefer Edit over Write on an existing file so the diff stays reviewable; Write is for scaffolding a file that isn't there.

Detect, never hardcode. Every fact comes from this repo at runtime. Nothing about jebel-quant/rhiza is assumed.

1. Detect the repo's facts

• Root + cleanliness — git rev-parse --show-toplevel, and note git status --porcelain. A dirty tree is fine (you're editing docs) but say what the user is mixing your changes with.
• Platform + OWNER/REPO from git remote get-url origin: github.com → GitHub; a GitLab host → GitLab. No remote ⇒ ask, or scaffold with OWNER/REPO placeholders and flag them.
• Default branch + visibility — one call, both platforms:

  uv run --python 3.12 --no-project python \
    "${CLAUDE_PLUGIN_ROOT}/scripts/platform_cli.py" repo-view --json
  

  It returns default_branch and visibility normalised, which matters: gh answers PUBLIC and glab answers public, so comparing the raw value gives a platform-dependent answer. Exit 1 (no CLI, or logged out) ⇒ fall back to main and treat visibility as unknown.
• Language, and therefore which manifest to read — ask rather than assume pyproject.toml:

  uv run --python 3.12 --no-project python "${CLAUDE_PLUGIN_ROOT}/scripts/language_profile.py" --json
  

  It returns the language, its manifest and its source_root. Exit 1 means undetermined — scaffold without language-specific facts rather than guessing Python.
• Project metadata — from the manifest that detection named. pyproject.toml: project.name, description, requires-python/classifiers (→ Python versions), license. Cargo.toml: [package] name, description, edition, license. go.mod: the module path and the go directive (→ Go version). From .rhiza/template.yml: the template ref.
• CI workflow — find .github/workflows -maxdepth 1 -name '*.yml', preferring one named *ci* (rhiza ships rhiza_ci.yml); or .gitlab-ci.yml. A badge must point at a workflow that exists.
• License — a LICENSE/LICENSE.md file and its SPDX id.
• Coverage service — a codecov.yml/.codecov.yml, a Codecov step in CI, or an existing coverage badge.
• ruff/uv usage — ruff.toml or a [tool.ruff] table; a uv.lock or uv_build backend. (Visibility comes from the repo-view call above, which — unlike the bare gh repo view --json visibility this used to name — also answers on GitLab.)