ARPAHLS · rosspeili · May 28, 2026 · May 28, 2026 · May 28, 2026
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -8,6 +8,12 @@ Contributors add user-facing entries under `[Unreleased]` in the same PR. Mainta
 
 ## [Unreleased]
 
+### Added
+- **Documentation**: Added [docs/vision.md](docs/vision.md) with project story, roadmap, and agent discoverability (#133).
+
+### Changed
+- **Documentation**: README Mission links to vision.md; wallet screening comparison table lives in COMPARISON.md; docs table and cross-links updated (#133).
+
 ## [0.3.2] - 2026-05-27
 
 ### Added

diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md
@@ -38,6 +38,10 @@ Human contributors and operators supervising **autonomous agents** or **AI-assis
 
 **Co-authoring:** Do not add AI tools or agents in `Co-authored-by:` commit trailers. Reserve co-author credits for **human** collaborators only. GitHub does not infer co-authors from normal commits; `Co-authored-by:` is added deliberately (web UI or commit message). Human pair or mob work should use that mechanism. AI assistance does not.
 
+**Skill contributors:** New skills must include **real issuer details** in `manifest.yaml` (`name`, `email`, and optional `github` / `org`) and matching attribution in skill docs and catalog entries. Placeholder or missing contact information is grounds for rejection. See [Issuer attribution](CONTRIBUTING.md#issuer-attribution) in [CONTRIBUTING.md](CONTRIBUTING.md) for the full checklist.
+
+**Disclaimers and promotion:** Skills may include short disclaimers, demos, or pointers to paid or extended versions when the copy is **accurate and safe**: real contact details, working links, and no misleading claims. Do not use fake emails, deceptive URLs, phishing, or promotional text that hides what the skill actually does. Maintainers review disclaimer and promo copy in manifests, instructions, and catalog pages. We may ask you to revise it, edit it ourselves, remove it, reject the skill, or restrict repeat offenders.
+
 ## Enforcement
 
 Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting the project team at [skillware-os@arpacorp.net](mailto:skillware-os@arpacorp.net). All complaints will be reviewed and investigated and will result in a response that is deemed necessary and appropriate to the circumstances. The project team is obligated to maintain confidentiality with regard to the reporter of an incident.
diff --git a/COMPARISON.md b/COMPARISON.md
@@ -1,11 +1,26 @@
 # Comparison: Skillware vs. Alternatives
 
-Skillware is a Python framework that decouples AI tool logic, cognition, and governance into self-contained, installable modules called **Skills**.
+Skillware is a Python framework that decouples AI tool logic, cognition, and governance into self-contained, installable modules called **Skills**. For the project story and roadmap, see [docs/vision.md](docs/vision.md).
 
 This document clarifies how Skillware compares to other common approaches for equipping AI agents with tools, including **Model Context Protocol (MCP)**, **Anthropic Skills**, **LangChain Tools**, **AutoGen**, and others.
 
 ---
 
+## Wallet screening: same task, different approaches
+
+**Screening an Ethereum wallet for sanctions and risk** — qualitative comparison across four methods:
+
+| Method | Speed | Cost | Accuracy | Reliability | Security | Setup |
+| :--- | :--- | :--- | :--- | :--- | :--- | :--- |
+| **Skillware** (`wallet_screening`) | Seconds | Low (~$0 + optional Etherscan key) | High (deterministic OFAC/TRM-style data) | Repeatable, tested Python | Fixed code path | `pip install skillware` |
+| **Prompt + web search** | Minutes | High tokens | Low (misses on-chain signals) | Varies per run | Generated code and scraping | Prompt engineering |
+| **MCP / multi-agent** | Minutes+ | Tokens + infra | Medium (tool-dependent) | Server/agent-dependent | Many moving parts | Deploy servers |
+| **Native APIs** (Chainalysis, TRM) | Sseconds | High (enterprise) | High | SLA-backed | Vendor-controlled | Contracts |
+
+Skill detail: [wallet_screening.md](docs/skills/wallet_screening.md). Multi-layer screening runs locally in one call via [`finance/wallet_screening`](skills/finance/wallet_screening/).
+
+---
+
 ## 1. Skillware vs. Model Context Protocol (MCP)
 
 The [Model Context Protocol](https://github.com/modelcontextprotocol) (MCP) is an open standard that connects AI models to data sources and tools via a client-server architecture.

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -314,6 +314,7 @@ Skill IDs follow `category/skill_name` and should match the path under `skills/`
 | [TESTING.md](docs/TESTING.md) | Black, Flake8, Pytest, local CI parity |
 | [Agent Code of Conduct](CODE_OF_CONDUCT.md) | Behavioral expectations for humans and agents |
 | [docs/introduction.md](docs/introduction.md) | Architecture: Mind, Body, Conscience |
+| [docs/vision.md](docs/vision.md) | Project story, roadmap, and agent discoverability |
 | [docs/skills/README.md](docs/skills/README.md) | Published skill catalog |
 | [templates/python_skill/](templates/python_skill/) | Boilerplate for new skills |
 | [Pull request template](.github/PULL_REQUEST_TEMPLATE.md) | PR checklist |

diff --git a/README.md b/README.md
@@ -19,9 +19,9 @@
   <a href="#architecture">Architecture</a> •
   <a href="#quick-start">Quick Start</a> •
   <a href="#documentation">Documentation</a> •
-  <a href="CHANGELOG.md">Changelog</a> •
   <a href="#contributing">Contributing</a> •
   <a href="#comparison">Comparison</a> •
+  <a href="CHANGELOG.md">Changelog</a> •
   <a href="#contact">Contact</a>
 </div>
 
@@ -33,18 +33,18 @@
 
 ## Mission
 
-The AI ecosystem is fragmented. Developers often re-invent tool definitions, system prompts, and safety rules for every project. **Skillware** supplies a standard to package capabilities into self-contained units that work across **Gemini**, **Claude**, **Ollama**, **GPT**, and **Llama**.
+The AI ecosystem is fragmented. Developers often re-invent tool definitions, system prompts, and safety rules for every project. **Skillware** supplies a standard to package capabilities into self-contained, installable units that work across **Gemini**, **Claude**, **Ollama**, **GPT**, and **Llama**. For the full story and roadmap, see our **[Vision](docs/vision.md)**.
 
 A **Skill** in this framework provides everything an Agent needs to master a domain:
 
-1.  **Logic**: Executable Python code.
-2.  **Cognition**: System instructions and "cognitive maps".
-3.  **Governance**: Constitution and safety boundaries.
-4.  **Interface**: Standardized schemas for LLM tool calling.
+1. **Logic**: Executable Python so agents run real work, not guess it.
+2. **Cognition**: System instructions and cognitive maps so any logical system uses the capability as intended.
+3. **Governance**: Constitution, safety boundaries, and hard limits baked into the bundle.
+4. **Interface**: Standardized tool schemas for any LLM or agent runtime.
 
 ### Skill library
 
-Browse capabilities by category in the [Skill library](docs/skills/README.md).
+Browse capabilities by category in the [Skill library](docs/skills/README.md) or on our <a href="https://skillware.site/skills" target="_blank" rel="noopener noreferrer">site&nbsp;↗</a>.
 
 ## Architecture
 
@@ -176,30 +176,23 @@ For other providers and shared integration patterns, see the [usage guides index
 
 ## Documentation
 
-| Topic | Link |
+| Topic | Links |
 | :--- | :--- |
-| Introduction | [docs/introduction.md](docs/introduction.md) |
-| Changelog | [CHANGELOG.md](CHANGELOG.md) |
-| Testing | [docs/TESTING.md](docs/TESTING.md) |
-| Skill library | [docs/skills/README.md](docs/skills/README.md) |
-| Usage guides | [index](docs/usage/README.md) — [Gemini](docs/usage/gemini.md) · [Claude](docs/usage/claude.md) · [OpenAI](docs/usage/openai.md) · [DeepSeek](docs/usage/deepseek.md) · [Ollama](docs/usage/ollama.md); [agent loops](docs/usage/agent_loops.md); [API keys](docs/usage/api_keys.md) |
-| Examples index | [examples/README.md](examples/README.md) |
-| CLI | [docs/usage/cli.md](docs/usage/cli.md) |
-| Contributing | [CONTRIBUTING.md](CONTRIBUTING.md) · [agent workflow](docs/contributing/ai_native_workflow.md) |
+| **Introduction** | [Introduction](docs/introduction.md) · [Vision](docs/vision.md) · [Comparison](COMPARISON.md) |
+| **Usage guides** | [Skill Library](docs/skills/README.md) · [Usage Guide](docs/usage/README.md) · [Examples](examples/README.md) · [Agent Loops](docs/usage/agent_loops.md) · [API Keys](docs/usage/api_keys.md) · [CLI](docs/usage/cli.md) |
+| **Contributing** | [Contributing](CONTRIBUTING.md) · [Agent Native Workflow](docs/contributing/ai_native_workflow.md) · [Testing](docs/TESTING.md) · [Changelog](CHANGELOG.md) |
 
 ## Contributing
 
-We are building the "App Store" for Agents and require professional, robust, and safe skills. We welcome contributions to the skill registry, documentation, tests, and core framework.
+We are building the "App Store" for Agents. Skills are the main contribution, but documentation, tests, and framework fixes are welcome too. Human operators and supervised agents follow the same standards: scoped PRs, deterministic behavior, and verified tests.
 
-* **[CONTRIBUTING.md](CONTRIBUTING.md)** — Contribution types, skill standard, pull request process, and navigation to all contributor docs.
-* **[Agent Contribution Workflow](docs/contributing/ai_native_workflow.md)** — Workflow for AI agents contributing to the repository (operators supervise).
-* **[Agent Code of Conduct](CODE_OF_CONDUCT.md)** — Deterministic outputs, safety boundaries, and acceptable use of skills.
-* **[TESTING.md](docs/TESTING.md)** — Local linting and pytest before you open a PR.
-* **[Pull request template](.github/PULL_REQUEST_TEMPLATE.md)** — Checklists for skills, docs, and framework changes (complete only the sections that apply).
+See the **Contributing** row in [Documentation](#documentation) for the full path, [Contributing](CONTRIBUTING.md) (types, skill standard, PR process), [Agent Native Workflow](docs/contributing/ai_native_workflow.md) (for autonomous and semi-autonomous agents), [Testing](docs/TESTING.md) (Black, Flake8, framework and skill pytest, pre-PR checklist), and [Changelog](CHANGELOG.md) (user-facing entries under `[Unreleased]`).
+
+Also read the [Agent Code of Conduct](CODE_OF_CONDUCT.md). Open PRs with the [pull request template](.github/PULL_REQUEST_TEMPLATE.md) and complete only the sections that apply.
 
 ## Comparison
 
-Skillware differs from the Model Context Protocol (MCP) or Anthropic's Skills repository in the following ways:
+Skillware differs from the Model Context Protocol (MCP), and Anthropic's Skills repository in several ways:
 
 *   **Model Agnostic**: Native adapters for Gemini, Claude, Ollama, and OpenAI.
 *   **Code-First**: Skills are executable Python packages, not just server specs.
@@ -212,8 +205,12 @@ Skillware differs from the Model Context Protocol (MCP) or Anthropic's Skills re
 For questions, suggestions, or contributions, please open an issue or reach out to us:
 
 *   **Email**: [skillware-os@arpacorp.net](mailto:skillware-os@arpacorp.net)
+*   **Enterprise**: [skills@arpacorp.net](mailto:skills@arpacorp.net) — enterprise skills, chaining, and forward deployed engineering
+*   **Security**: [security@arpacorp.net](mailto:security@arpacorp.net) — report bugs, vulnerabilities, or other sensitive issues (see [SECURITY.md](SECURITY.md))
 *   **Issues**: [GitHub Issues](https://github.com/arpahls/skillware/issues)
 
+For skill-specific questions or reaching a skill's maintainer, check issuer and author details on the skill card, in the repo [Skill Library](docs/skills/README.md), or on our website's <a href="https://skillware.site/skills" target="_blank" rel="noopener noreferrer">skills catalog&nbsp;↗</a>.
+
 ---
 
 <div align="center">

diff --git a/docs/contributing/ai_native_workflow.md b/docs/contributing/ai_native_workflow.md
@@ -339,6 +339,7 @@ Run this internal dialogue before you hand off to your operator.
 ## Related documents
 
 - [CONTRIBUTING.md](../../CONTRIBUTING.md) — contribution hub and skill standard
+- [Vision](../vision.md) — project story and roadmap
 - [TESTING.md](../TESTING.md) — Black, Flake8, Pytest
 - [Usage guides](../usage/README.md) — provider adapters (`to_gemini_tool`, `to_openai_tool`, etc.)
 - [Agent loops](../usage/agent_loops.md) — shared load / execute / tool-result pattern

diff --git a/docs/introduction.md b/docs/introduction.md
@@ -103,6 +103,7 @@ Skillware is designed to be the "Standard Library" for all agents.
 
 ---
 **Next Steps:**
+*   Read the [Vision](vision.md) (story, roadmap, and where we are today)
 *   Explore the [Skill Library](skills/README.md)
 *   Browse the [Runnable Examples Index](../examples/README.md)
 *   View the [Changelog](../CHANGELOG.md) for release history