docs: post-release documentation alignment (#154)

.env.example

@@ -18,3 +18,11 @@ DEEPSEEK_API_KEY="your_deepseek_key_here"
 # Create a fine-grained PAT with read-only Contents + Issues access:
 # https://github.com/settings/personal-access-tokens/new
 GITHUB_TOKEN="github_pat_..."
+
+# DeFi / EVM agent wallet (defi/evm_tx_handler)
+# Use a dedicated agent wallet with limited funds — never a personal or treasury wallet.
+# Preview and dry-run before live transfers. Never commit real private keys.
+# AGENT_WALLET_PRIVATE_KEY="0x..."
+# ETHEREUM_RPC_URL="https://..."
+# BASE_RPC_URL="https://..."
+# COINGECKO_API_KEY="optional_for_usd_caps"

CHANGELOG.md

@@ -13,6 +13,7 @@ Contributors add user-facing entries under `[Unreleased]` in the same PR. Mainta
 - **Tests**: `tests/test_skill_issuer.py` now requires `test_skill.py` for every registry skill under `skills/` (#160).
 - **Documentation**: Clarified that bundle tests must mock network calls and model downloads in CI (#170).
 - **Documentation**: Added a **Status** section to [TESTING.md](docs/TESTING.md) summarizing the current testing model and planned CLI work (#179).
+- **Documentation**: Post-release alignment — category tables, Python 3.10+ badge, dev install (`[dev,all]` vs `[dev]`), README configuration via `.env.example`, DeFi env vars in `.env.example`, framework env vars in [api_keys.md](docs/usage/api_keys.md) (#154).
 
 ## [0.3.7] - 2026-06-22
 

CONTRIBUTING.md

@@ -79,6 +79,8 @@ git checkout -b feat/issue-<number>-short-description
 pip install -e ".[dev,all]"
 ```
 
+For documentation-only PRs, `pip install -e ".[dev]"` is sufficient. For skill or framework work, use `[dev,all]` to match CI.
+
 See [TESTING.md](docs/TESTING.md) for the bundle / framework / maintainer / example model and pytest usage.
 
 ### 5. Implement and verify
@@ -98,7 +100,7 @@ Follow the [Agent Code of Conduct](CODE_OF_CONDUCT.md): deterministic skill outp
 ### Style
 
 - **No emojis** in source code, documentation, commit messages, or PR titles.
-- Use **Black** for formatting and **Flake8** for linting (see [TESTING.md](docs/TESTING.md)).
+- Use **Black** for formatting (CI runs `black --check`) and **Flake8** for linting (see [TESTING.md](docs/TESTING.md)).
 - Match existing naming, structure, and documentation tone in the files you touch.
 
 ### Scope
@@ -308,14 +310,15 @@ Place each skill under one top-level directory under `skills/`. Use an existing
 | Category | Purpose | Examples in registry |
 | :--- | :--- | :--- |
 | `compliance` | Privacy, policy, regulatory guardrails | `pii_masker`, `mica_module`, `tos_evaluator` |
-| `data_engineering` | Datasets, generation, ETL-style tooling | `synthetic_generator` |
-| `finance` | Blockchain, risk, financial analysis | `wallet_screening` |
+| `data_engineering` | Datasets, generation, ETL-style tooling | `synthetic_generator`, `novelty_extractor` |
 | `defi` | On-chain trading and agent wallet execution | `evm_tx_handler` |
+| `dev_tools` | Developer workflows, issue resolution, repo tooling | `issue_resolver` |
+| `finance` | Blockchain, risk, financial analysis | `wallet_screening` |
 | `office` | Documents, productivity | `pdf_form_filler` |
 | `optimization` | Middleware, compression, efficiency | `prompt_rewriter` |
 | `wellness` | Coaching guardrails, mental health support | `mental_coach` |
 
-Skill IDs follow `category/skill_name` and should match the path under `skills/`.
+Skill IDs follow `category/skill_name` and should match the path under `skills/`. For the live registry, see [Skill Library](docs/skills/README.md). Propose new top-level categories in an issue before adding a folder.
 
 ---
 
@@ -332,7 +335,7 @@ Skill IDs follow `category/skill_name` and should match the path under `skills/`
 
 ## Safety and security
 
-- Skills that touch real-world assets (wallets, email, production APIs) should support a **dry run** or read-only mode when feasible.
+- Skills that touch real-world assets (wallets, email, production APIs) should support a **dry run** or read-only mode when feasible. High-risk skills (on-chain transfers, wallet operations) should use preview and confirmation flows before sending transactions; read each skill's instructions before enabling live keys.
 - Sanitize inputs in `skill.py` before external calls.
 - Respect the skill `constitution` in both code and documentation.
 - Malicious or deceptive contributions may be rejected and blocked from the project.

README.md

@@ -8,7 +8,7 @@
 
 <div align="center">
   <img src="https://img.shields.io/badge/License-MIT-efcefa?style=flat-square" alt="License">
-  <img src="https://img.shields.io/badge/Python-3.11+-bae6fd?style=flat-square" alt="Python Version">
+  <img src="https://img.shields.io/badge/Python-3.10+-bae6fd?style=flat-square" alt="Python Version">
   <a href="https://pypi.org/project/skillware/"><img src="https://img.shields.io/pypi/v/skillware?style=flat-square&color=bbf7d0" alt="PyPI Version"></a>
 </div>
 
@@ -79,6 +79,8 @@ Skillware/
 
 ## Quick Start
 
+Requires **Python 3.10 or newer** (see `requires-python` in `pyproject.toml`).
+
 ### 1. Installation
 
 You can install Skillware directly from PyPI:
@@ -92,9 +94,11 @@ Or for development, clone the repository and install in editable mode:
 ```bash
 git clone https://github.com/arpahls/skillware.git
 cd skillware
-pip install -e .
+pip install -e ".[dev,all]"
 ```
 
+For documentation-only work, `pip install -e ".[dev]"` is enough. Skill and framework contributors should use `[dev,all]` to match CI (see [TESTING.md](docs/TESTING.md)).
+
 > **Note**: Individual skills may have their own dependencies. The `SkillLoader` validates `manifest.yaml` and warns of missing packages (e.g., `requests`, `pandas`) upon loading a skill.
 
 ### 2. Verify your installation
@@ -113,12 +117,22 @@ your PATH — use `python -m skillware list` as a fallback. See
 
 ### 3. Configuration
 
-Create a `.env` file with your API keys (e.g., Google Gemini API Key):
+Copy the environment template and add your keys.
+
+**Unix / macOS:**
+
+```bash
+cp .env.example .env
+```
 
-```ini
-GOOGLE_API_KEY="your_key"
+**Windows (PowerShell):**
+
+```powershell
+Copy-Item .env.example .env
 ```
 
+Edit `.env` with agent keys (for example Gemini) and any keys your skills need. Agent keys power your LLM client; skill keys are declared per skill in the [Skill library](docs/skills/README.md). See [API keys for skills](docs/usage/api_keys.md) for setup, security, and framework variables.
+
 ### 4. Usage Example (Gemini)
 
 This example requires the Google SDK optional extra: `pip install "skillware[gemini]"` (local dev: `pip install -e ".[gemini]"`). See the [Gemini usage guide](docs/usage/gemini.md) for setup details.

docs/TESTING.md

@@ -100,7 +100,7 @@ Run Black on the entire repository to automatically fix formatting issues:
 python -m black .
 ```
 
-Run `python -m black --check .` to verify formatting without writing files. GitHub Actions runs the same check before flake8 and pytest.
+Run `python -m black --check .` to verify formatting without writing files. GitHub Actions runs the same check on every pull request before flake8 and pytest; run `python -m black .` locally to fix issues before you push.
 
 ## 2. Linting (Flake8)
 

docs/contributing/ai_native_workflow.md

@@ -55,6 +55,8 @@ pip install -e ".[dev,all]"
 git checkout -b feat/issue-<number>-short-description
 ```
 
+Use `pip install -e ".[dev]"` when the issue is documentation-only; use `[dev,all]` for skill or framework work so local pytest matches CI.
+
 Before Stage 2, confirm:
 
 - Correct issue number and branch name
@@ -225,7 +227,7 @@ These align with [CONTRIBUTING.md](../../CONTRIBUTING.md). Violations block merg
 - `card.json` issuer must match manifest `name` and `email` when present
 - Update `docs/skills/<skill_name>.md` and `docs/skills/README.md`
 - On each catalog page, add a **Usage Examples** section (Gemini, Claude, OpenAI, DeepSeek, Ollama prompt mode) per [skill usage template](../usage/skill_usage_template.md). Keep provider mechanics in `docs/usage/`; put skill-specific paths, sample user messages, and `execute` payloads on the skill page.
-- Categories: `compliance`, `data_engineering`, `finance`, `office`, `optimization`—propose new ones in the issue first
+- Categories: `compliance`, `data_engineering`, `defi`, `dev_tools`, `finance`, `office`, `optimization`, `wellness` — see [Skill library](../skills/README.md) for the live registry; propose new top-level categories in the issue first
 - Do not bump `pyproject.toml` version in skill-only PRs unless requested
 - Logic in `skill.py`; prompts and persona in `instructions.md`
 - Never commit secrets; document `env_vars` in the manifest

docs/skills/README.md

@@ -23,7 +23,7 @@ On-chain execution and trading for dedicated agent wallets (structured intent, p
 
 | Skill | ID | Issuer | Description |
 | :--- | :--- | :--- | :--- |
-| **[EVM Transaction Handler](evm_tx_handler.md)** | `defi/evm_tx_handler` | [@Hendobox](https://github.com/Hendobox) | Uni V2 quote, preview, execute, and transfer on Ethereum/Base from structured intent (#142). |
+| **[EVM Transaction Handler](evm_tx_handler.md)** | `defi/evm_tx_handler` | [@Hendobox](https://github.com/Hendobox) | Uni V2 quote, preview, execute, and transfer on Ethereum/Base from structured intent. |
 
 ## Optimization
 Middleware skills that operate on text or state to increase performance, security, or efficiency.
@@ -61,7 +61,7 @@ Supportive coaching guardrails, crisis triage, and grounded psychoeducation for
 
 | Skill | ID | Issuer | Description |
 | :--- | :--- | :--- | :--- |
-| **[Mental Coach](mental_coach.md)** | `wellness/mental_coach` | [@mrmasa88](https://github.com/mrmasa88) (AO) | Deterministic wellness coaching firewall with crisis triage, scope limits, and cited KB retrieval (#148). |
+| **[Mental Coach](mental_coach.md)** | `wellness/mental_coach` | [@mrmasa88](https://github.com/mrmasa88) (AO) | Deterministic wellness coaching firewall with crisis triage, scope limits, and cited KB retrieval. |
 
 ---
 

docs/usage/api_keys.md

@@ -7,6 +7,7 @@ Many Skillware skills call external services (block explorers, model APIs, and s
 ## Navigation
 
 - [Skill keys vs agent keys](#skill-keys-vs-agent-keys)
+- [Framework environment variables](#framework-environment-variables)
 - [Local development](#local-development)
 - [Cloud and CI](#cloud-and-ci)
 - [Secret managers](#secret-managers)
@@ -27,6 +28,19 @@ A single workflow may need both: for example, a skill that screens wallets may r
 
 ---
 
+## Framework environment variables
+
+These are read by Skillware itself (loader and CLI), not by individual skills:
+
+| Variable | Purpose |
+| :--- | :--- |
+| `SKILLWARE_SKILL_PATH` | Extra filesystem roots for skill discovery (OS path separator between multiple entries). See [CLI reference](cli.md#path-resolution). |
+| `SKILLWARE_NO_VERSION_CHECK` | Set to `1` to disable the CLI version advisory (useful in CI and automation). See [CLI reference](cli.md#version-advisory). |
+
+Skill-specific names remain on each skill's catalog page and in `manifest.yaml` `env_vars`.
+
+---
+
 ## Local development
 
 ### `.env` file (recommended)

requirements.txt

@@ -1,5 +1,6 @@
 # Development convenience — same install GitHub Actions CI uses (see pyproject.toml).
 # Installs core + dev tools (pytest, flake8, black) + all optional SDK extras.
+# Documentation-only PRs can use: pip install -e ".[dev]"
 # For production installs use pyproject.toml extras instead, e.g.:
 #   pip install skillware                  # core only
 #   pip install "skillware[gemini]"        # + Google Gemini SDK