[Docs]: README refresh and new docs/vision.md

[rosspeili]

What needs to be fixed?

Skillware needs a clearer public narrative than the current README alone provides. A long form Substack piece already exists (skills.md is Dead). The repo should distill that story into official docs without bloating the README or duplicating COMPARISON.md.

Goal

Create docs/vision.md as the canonical storytelling doc. Lightly reshape README.md so it stays scannable while pointing readers to vision.md for depth.

New file: docs/vision.md

Readable self contained doc (roughly 800 to 1500 words). Suggested sections:

Opening
What Skillware is and why installable capability matters.

How we started
Fragmentation pain. The apt/pip analogy. Optional Substack link as extended reading.

Why not instructions only
Limits of markdown only flows and web search for deterministic work. Executable Python, bundled data, tests, governance in one bundle. Factual tone.

Wallet screening as narrative example
Use finance/wallet_screening in prose to explain multi layer local screening. No comparison table here. Link to README Comparison section or docs/skills/wallet_screening.md for the matrix.

Built for agents
Manifests, skillware list, examples index, provider guides, agent workflow, copy paste snippets. How agents discover, vet, and integrate without reinventing skills.

Roadmap in four phases
One short example each:

1. Now Modular skills for existing LLMs
2. Next Ultimate skills with industry partners
3. World skills Robots, drones, appliances
4. Brain skills BCI scale skill delivery

Mark future phases as roadmap.

Where we are today
Honest snapshot (registry, loader, CLI, v0.3.x, active work like wallet_screening RFC). Link to good first issues.

Join us
Contributor invite for humans and supervised agents. Links to CONTRIBUTING and agent workflow.

README changes

Mission
Tighten one paragraph. Add link: full vision → docs/vision.md

Comparison section (existing ## Comparison)
Keep current bullet list and COMPARISON.md hyperlink unchanged below.

Add above those bullets: a minimal comparison table for the wallet screening task across four approaches:

• Skillware (wallet_screening)
• Prompt or skills.md style (search and generated logic)
• MCP or multi agent orchestration
• Native compliance APIs

Suggested columns (keep row count small): Speed, Cost, Accuracy, Reliability, Security, Setup effort.

Use qualitative labels (e.g. high/medium/low or short phrases). Avoid hardcoded dollar figures or token counts unless easy to maintain. One line under the table pointing to wallet_screening for skill detail.

Do not add a separate "Why Skillware" section for the table. The table belongs only under Comparison.

Documentation table
Add row: Vision → docs/vision.md

Navigation
Link to vision.md from top nav or Mission as appropriate.

Other cross links

• docs/introduction.md — Vision in Next Steps or opening
• CONTRIBUTING.md or docs/contributing/ai_native_workflow.md — optional one line to vision.md
• COMPARISON.md — optional one sentence at top pointing to vision.md for story and roadmap

Style

Short sentences. Avoid semicolons and em dashes in new prose where possible. README stays minimal. vision.md carries the story. Table stays in README Comparison only.

Acceptance criteria

• docs/vision.md exists with story, roadmap, agent discoverability, current state, contributor invite (no comparison table inside)
• README Mission links to vision.md
• README Comparison section has minimal wallet screening table above existing bullets and COMPARISON.md link
• Existing Comparison bullets and COMPARISON.md link preserved
• README documentation table lists vision.md
• docs/introduction.md links to vision.md
• At least one contributor doc links to vision.md
• All relative links resolve on GitHub

Rationale

README Comparison is already where readers look for alternatives. A small wallet screening table there makes the value concrete without expanding Mission or duplicating COMPARISON.md. vision.md holds the long arc. COMPARISON.md stays the deep technical contrast doc.

Implementation Idea

New: docs/vision.md

Edit: README.md (Mission tweak, Comparison table insert, docs table row)

Light touch: docs/introduction.md, optional CONTRIBUTING or ai_native_workflow link, optional COMPARISON.md one liner

Table placement: inside existing ## Comparison, immediately after the section heading and optional one sentence intro, before the three bullets and COMPARISON.md link

Screening an Ethereum wallet for sanctions and risk — same task, different approaches:

Method	Speed	Cost	Accuracy	Reliability	Security
Skillware (wallet_screening)	Seconds	~$0 (+ optional Etherscan key)	High — deterministic OFAC/TRM-style data	Repeatable, tested Python	Fixed code path
Prompt + web search	Minutes	High tokens	Low — misses on-chain signals	Varies per run	Generated code & scraping
MCP / multi-agent	Slow	Tokens + infra	Medium — tool-dependent	Server/agent-dependent	Many moving parts
Native APIs (Chainalysis, TRM)	Fast	$$$ enterprise	High	SLA-backed	Vendor-controlled

Setup: pip install skillware vs. prompt engineering vs. deploying servers vs. contracts. Multi-layer screening runs locally in one call. Details · Full comparison

Out of Scope

• Rewriting COMPARISON.md body
• Comparison table inside vision.md
• Marketing site changes
• Code or manifest changes
• Hardcoded benchmarks that need frequent updates

Affected Page

docs/vision.md (new), README.md, docs/introduction.md, CONTRIBUTING.md or docs/contributing/ai_native_workflow.md (optional), COMPARISON.md (optional)