[Docs]: Post-release documentation alignment (categories, install, env vars, CLI, Python version)

[rosspeili]

What needs to be fixed?

After #135, #142, and #153 land, do a single documentation alignment pass so user-facing and contributor docs match the repo. An audit found no structural doc problems, but several small inconsistencies that are easier to fix in one PR than piecemeal.

Do not start this issue until blockers #135, #142, and #153 are closed/merged (CLI/rich-in-core, defi skill, Black CI). Otherwise we will edit the same files twice.

Summary

One coordinated docs PR that:

1. Syncs skill category tables with the live registry
2. Harmonizes dev install instructions ([dev] vs [dev,all])
3. Fixes Python version messaging (badge vs pyproject.toml vs CI)
4. Improves env var discoverability for new users (README + .env.example)
5. Finishes CLI install/PATH docs after rich moves to core ([Feat]: CLI discoverability, PATH docs, python -m skillware, and unified help #135)
6. Updates TESTING.md after Black is gated in CI ([Feat]: Format codebase with Black and gate CI on black --check #153)
7. Optionally adds a short framework env vars reference (non-secret names only)

Blockers

Blocker	Why we wait
#135 / PR #147	rich in core, python -m skillware, PATH docs, unified help, sweep of stale skillware[cli] mentions
#142 / PR #150	New defi category, catalog page, skill env_vars (e.g. wallet private key), .env.example entries
#153	Repo-wide Black format + black --check in CI; TESTING/CONTRIBUTING must describe gated Black, not "CI does not gate yet"

Scope / Checklist

1. Skill categories (registry ↔ contributor docs)

• CONTRIBUTING.md — Skill categories table: add dev_tools (already in catalog); add defi after [New Skill]: defi/evm_tx_handler — NLP-driven agent wallet for EVM buy/sell/send #142 merges
• docs/contributing/ai_native_workflow.md — Same category list under "Skillware rules you must follow"
• Optional one-liner in both: "Current registry: see docs/skills/README.md; propose new categories in the issue first"

2. Dev install command consistency

• CONTRIBUTING.md Getting started — align with CI: recommend pip install -e ".[dev,all]" for skill/framework work; note [dev] alone is enough for docs-only PRs
• docs/contributing/ai_native_workflow.md Stage 1 — same wording as CONTRIBUTING/TESTING
• Confirm requirements.txt comment still accurate (already points at [dev,all])

3. Python version badge

• README.md badge: change 3.11+ → 3.10+ to match requires-python = ">=3.10" and CI matrix (3.10–3.12)
• Optional: one sentence in Quick Start if helpful ("Python 3.10 or newer")

4. Env vars — user onboarding

• README.md § Configuration — replace bare GOOGLE_API_KEY-only snippet with:
  • cp .env.example .env (or Windows equivalent)
  • Link to docs/usage/api_keys.md
  • Note: agent keys vs skill keys; per-skill names on catalog pages
• .env.example — after [New Skill]: defi/evm_tx_handler — NLP-driven agent wallet for EVM buy/sell/send #142: add DeFi skill vars from defi/evm_tx_handler manifest (with comment: never commit; dry-run first). Keep generic agent keys as today
• docs/usage/api_keys.md — optional short subsection or table listing framework env vars only (not every skill):
  • SKILLWARE_SKILL_PATH
  • SKILLWARE_NO_VERSION_CHECK
  • Link to cli.md / usage README for detail

5. CLI docs (after #135 / #147)

Sweep stale skillware[cli] install language now that rich is core:

• README.md Quick Start — pip install skillware then skillware list; PATH note + python -m skillware fallback (per merged [Feat]: CLI discoverability, PATH docs, python -m skillware, and unified help #135 docs)
• docs/usage/cli.md — ensure "Running the CLI" section from [Feat]: CLI discoverability, PATH docs, python -m skillware, and unified help #135 is present; remove "requires [cli] extra" where obsolete; keep [cli] as deprecated alias only if still in pyproject
• docs/skills/README.md, docs/vision.md, requirements.txt header comments — same install simplification
• docs/contributing/ai_native_workflow.md / TESTING.md pre-PR checklist — skillware list without extra install step

6. Testing docs (after #153)

• docs/TESTING.md — Black section: CI does run black --check; local python -m black . before PR
• CONTRIBUTING.md — Universal expectations / PR process: mention Black is CI-gated (brief; link TESTING.md)
• Remove or update "CI does not gate on Black yet" language everywhere it appears

7. DeFi catalog (after #142 / #150)

• docs/skills/README.md — defi section + row for evm_tx_handler
• docs/skills/evm_tx_handler.md — only if not already in skill PR; otherwise verify cross-links
• examples/README.md — row if example script ships with skill PR
• CONTRIBUTING Safety section — optional one line pointing high-risk skills (wallets, transfers) to dry-run / read-only patterns (no duplicate of skill instructions)

8. Out of scope (do not expand this issue)

• Implementing CLI features ([Feat]: CLI commands to set and repair skill directory paths (sub-issue of #16) #81 paths, [Feat]: CLI command to run skill tests (sub-issue of #16) #83 test)
• uv adoption ([RFC]: Where uv could benefit Skillware, install tooling, reproducibility, and dependency workflows #149)
• Rewriting skill catalog Usage Examples
• introduction.md "Local LLaMA (Planned) GBNF" roadmap line (harmless; change only if touched for another reason)

Acceptance Criteria

• Blockers [Feat]: CLI discoverability, PATH docs, python -m skillware, and unified help #135, [New Skill]: defi/evm_tx_handler — NLP-driven agent wallet for EVM buy/sell/send #142, [Feat]: Format codebase with Black and gate CI on black --check #153 are closed before work starts
• Category tables in CONTRIBUTING and ai_native_workflow match docs/skills/README.md (including dev_tools and defi)
• Dev install guidance is consistent: [dev,all] for CI parity; [dev] called out for docs-only
• README Python badge matches pyproject (>=3.10)
• README Configuration points to .env.example and api_keys.md
• No stale "you must pip install skillware[cli]" for basic CLI use (unless documenting deprecated extra)
• cli.md documents PATH + python -m skillware per merged [Feat]: CLI discoverability, PATH docs, python -m skillware, and unified help #135
• TESTING.md reflects Black gated in CI per [Feat]: Format codebase with Black and gate CI on black --check #153
• .env.example includes new DeFi vars from merged skill manifest (commented, with security note)
• Optional: framework env var names documented in one place (api_keys or usage README)
• flake8 pass; pytest tests/ pass; contributor ran black --check locally
• CHANGELOG [Unreleased] Documentation bullet for this sweep

Implementation Notes

Single PR, docs-only (plus .env.example comments). Good first issue once blockers clear.

Suggested order after blockers merge:

1. Rebase on latest main
2. Grep repo for skillware[cli], 3.11+, [dev] without all, "CI does not gate on Black"
3. Apply checklist; one CHANGELOG entry
4. Self-check: fresh clone → follow README Quick Start → skillware list works without remembering extras

Related

• [Feat]: CLI discoverability, PATH docs, python -m skillware, and unified help #135 — CLI discoverability (PR Add __main__.py, cmd_help, --version, and move rich to core #147)
• [New Skill]: defi/evm_tx_handler — NLP-driven agent wallet for EVM buy/sell/send #142 — defi/evm_tx_handler (PR feat(defi): add evm_tx_handler PR1 (quote, preview, transfer) #150)
• [Feat]: Format codebase with Black and gate CI on black --check #153 — Black + CI
• [Feat]: Align CI with pyproject extras, skill tests, and manifest dependencies #151 — CI pytest scope (already merged; do not regress pytest tests/ wording)

Affected Page

README.md, .env.example, CONTRIBUTING.md, docs/TESTING.md, docs/usage/cli.md, docs/usage/api_keys.md, docs/usage/README.md, docs/contributing/ai_native_workflow.md, docs/skills/README.md, docs/vision.md, requirements.txt, CHANGELOG.md