automaintainer: Improve supercli static documentation: README, CONTRIBUTING…

CONTRIBUTING.md

@@ -215,6 +215,38 @@ docs(readme): update installation instructions
   - `/docs/features/` — Feature-specific documentation (adapters, skills, workflows, etc.)
 - Plugin-specific docs in `/plugins/*/README.md`
 
+### Documentation Map
+
+This map shows how docs relate to each other, so you can find related reading fast:
+
+```
+README.md
+├── CONTRIBUTING.md (you are here)
+│   ├── PLUGIN_STANDARDS.md ──── description, tag, source URL rules
+│   └── TAG_VOCABULARY.md ──── controlled vocabulary reference
+├── ARCHITECTURE_PLAN.md ──── design decisions, CI/CD status
+├── docs/
+│   ├── plugins-how-to.md ──── plugin harness development
+│   │   ├── plugins-examples.md ──── real plugin manifests
+│   │   └── features/README.md ──── feature deep-dives
+│   ├── AGENTS_FRIENDLY_TOOLS.md ──── agent-first CLI principles
+│   ├── skills-catalog.md ──── SKILL.md provider system
+│   ├── server-plugins-usage-guide.md ──── server plugin testing
+│   ├── ROADMAP.md ──── 2026-2028 product direction
+│   └── feature-gaps.md ──── what's missing vs. capability-mesh vision
+└── plugins/<name>/
+    ├── plugin.json ──── command manifest
+    ├── meta.json ──── registry metadata (description, tags)
+    └── README.md ──── optional human docs
+```
+
+**Key relationships:**
+- `PLUGIN_STANDARDS.md` ↔ `TAG_VOCABULARY.md` — tag rules reference the vocabulary
+- `plugins-how-to.md` → `plugins-examples.md` — how-to explains, examples show
+- `AGENTS_FRIENDLY_TOOLS.md` → `features/agent-friendly.md` — principles → implementation
+- `skills-catalog.md` → `features/skills.md` — catalog system → skill document format
+- `ROADMAP.md` ↔ `feature-gaps.md` — roadmap items address feature gaps
+
 ### Documentation Style
 
 - Use clear, concise language

docs/features/README.md

@@ -19,9 +19,55 @@ Detailed documentation for supercli's core features and capabilities.
 | [Azure DevOps & UiPath Plugins](azd-uipath-plugins.md) | Azure Developer CLI and UiPath automation harnesses | [Read →](azd-uipath-plugins.md) |
 | [Server Plugins Usage Guide](../server-plugins-usage-guide.md) | Manual testing of server plugins including JSON and ZIP flows | [Read →](../server-plugins-usage-guide.md) |
 
+## By Category
+
+### Core Engine
+Features that power the routing and execution backbone:
+
+- **[Adapters](adapters.md)** — The four adapter types (CLI, MCP, HTTP, Workflow) that bridge external tools into the capability graph.
+- **[Storage](storage.md)** — Persistence layer for plugin state, lockfiles, and installed capabilities.
+- **[Config Sync](config-sync.md)** — Keeps client plugin state synchronized with remote server registries.
+
+### AI & Agent Integration
+Features designed for programmatic and AI-agent consumption:
+
+- **[Agent-Friendly Tooling](agent-friendly.md)** — Design principles: semantic exit codes, structured output, deterministic schemas.
+- **[Skill Documents](skills.md)** — SKILL.md catalog system that teaches agents how to use specific tools.
+- **[Natural Language Execution](ask.md)** — Translates `supercli ask "do X and Y"` into multi-capability execution workflows.
+- **[Execution Plans](execution-plans.md)** — Step-by-step planning and execution of complex command sequences.
+
+### Server & Distribution
+Features for running supercli as a service or distributing plugins:
+
+- **[Server Plugins](server-plugins.md)** — Server-side plugin distribution via JSON and ZIP flows.
+- **[Server Plugins Usage Guide](../server-plugins-usage-guide.md)** — Hands-on testing guide for server plugin endpoints.
+- **[Observability](observability.md)** — Job tracing, execution history, and performance metrics.
+
+### Domain Integrations
+Specialized plugin harnesses:
+
+- **[Azure DevOps & UiPath Plugins](azd-uipath-plugins.md)** — Azure Developer CLI and UiPath RPA automation harnesses.
+
+### Multi-Step Automation
+Composing multiple capabilities into workflows:
+
+- **[Workflows](workflows.md)** — Multi-step execution with data piping between capabilities.
+
 ## Quick Navigation
 
 - **New to supercli?** Start with [README.md](../../README.md)
 - **Plugin development?** See [plugins-how-to.md](../plugins-how-to.md)
 - **Contributing?** See [CONTRIBUTING.md](../../CONTRIBUTING.md)
 - **Architecture details?** See [ROADMAP.md](../ROADMAP.md)
+
+## Choosing a Feature
+
+| If you need to... | Start with... |
+|---|---|
+| Add a new CLI tool to supercli | [plugins-how-to.md](../plugins-how-to.md) (not here — that's the plugin guide) |
+| Understand how adapters work | [Adapters](adapters.md) |
+| Design an agent-friendly CLI | [Agent-Friendly Tooling](agent-friendly.md) |
+| Chain multiple commands together | [Workflows](workflows.md) or [Natural Language Execution](ask.md) |
+| Deploy supercli as a server | [Server Plugins](server-plugins.md) + [Usage Guide](../server-plugins-usage-guide.md) |
+| Add a skill document for agents | [Skill Documents](skills.md) |
+| Debug execution failures | [Observability](observability.md) |

docs/plugins-how-to.md

@@ -406,14 +406,80 @@ supercli plugins show my-plugin
 supercli plugins doctor my-plugin
 ```
 
-### Validation
+### Validation Checklist
+
+Run these checks before submitting a plugin:
+
+**1. Manifest syntax and required fields:**
 
 ```bash
-# Check syntax of plugin.json
-cat plugins/my-plugin/plugin.json | jq .
+# Validate JSON syntax
+jq . plugins/my-plugin/plugin.json
+jq . plugins/my-plugin/meta.json
+
+# Check required plugin.json fields
+jq '{name, version, description, source}' plugins/my-plugin/plugin.json
+
+# Check required meta.json fields
+jq '{description, tags}' plugins/my-plugin/meta.json
+
+# Verify tags count (must be 3-8)
+jq '.tags | length' plugins/my-plugin/meta.json
 
-# Verify binary detection
+# Verify description length (must be 30-150 chars)
+jq '.description | length' plugins/my-plugin/meta.json
+```
+
+**2. Command definitions:**
+
+```bash
+# List all commands your plugin exposes
+jq '.commands[] | {namespace, resource, action}' plugins/my-plugin/plugin.json
+
+# Verify each command has required fields
+jq '.commands[] | {adapter, description}' plugins/my-plugin/plugin.json
+
+# Check that adapterConfig has the binary name
+jq '.commands[] | select(.adapter=="process") | .adapterConfig.command' plugins/my-plugin/plugin.json
+```
+
+**3. Binary dependency:**
+
+```bash
+# Verify the required binary is in PATH
 which my-cli
+
+# Verify the binary runs
+my-cli --version
+
+# Check install-guidance.json if present
+jq . plugins/my-plugin/install-guidance.json
+```
+
+**4. Discovery and inspection:**
+
+```bash
+# Verify supercli discovers the plugin
+supercli plugins explore --name my-plugin
+
+# Inspect command argument schemas
+supercli inspect my-plugin resource action
+
+# Verify commands appear in listing
+supercli commands --namespace my-plugin
+```
+
+**5. Execution smoke test:**
+
+```bash
+# Run with --json to verify structured output
+supercli my-plugin resource action --json
+
+# Run with --verbose for debugging
+supercli my-plugin resource action --verbose
+
+# Show the planned command before execution
+supercli plan my-plugin resource action --args
 ```
 
 ### Debugging