automaintainer: Improve supercli static documentation: README, CONTRIBUTING…

CONTRIBUTING.md

@@ -198,18 +198,31 @@ docs(readme): update installation instructions
 
 ### Where to Find Documentation
 
-- `/docs/` - Main documentation directory
-- `/docs/plugins-how-to.md` - Plugin development guide
-- `/docs/skills-catalog.md` - Skill document catalog and provider management
-- `/README.md` - Project overview and quick start
+- `/README.md` — Project overview and quick start
+- `/CONTRIBUTING.md` — This file
+- `/PLUGIN_STANDARDS.md` — Plugin quality standards (descriptions, tags, source URLs)
+- `/TAG_VOCABULARY.md` — Controlled vocabulary for plugin tags
+- `/ARCHITECTURE_PLAN.md` — Architecture plan and design decisions
+- `/docs/` — Main documentation directory
+  - `/docs/plugins-how-to.md` — Plugin development guide
+  - `/docs/skills-catalog.md` — Skill document catalog and provider management
+  - `/docs/server-plugins-usage-guide.md` — Server plugin usage and testing guide
+  - `/docs/AGENTS_FRIENDLY_TOOLS.md` — Agent-friendly CLI design principles
+  - `/docs/ROADMAP.md` — Project roadmap (2026–2028)
+  - `/docs/feature-gaps.md` — Feature gap analysis vs. capability-mesh vision
+  - `/docs/plugins-available.md` — Available plugins listing
+  - `/docs/plugins-examples.md` — Plugin examples
+  - `/docs/features/` — Feature-specific documentation (adapters, skills, workflows, etc.)
 - Plugin-specific docs in `/plugins/*/README.md`
 
 ### Documentation Style
 
 - Use clear, concise language
-- Include practical examples
-- Keep code snippets up to date
-- Use consistent formatting
+- Include practical examples with copy-pasteable commands
+- Keep code snippets up to date with current CLI syntax
+- Use consistent formatting: `backticks` for commands, **bold** for key concepts
+- Reference other docs files when relevant (e.g., "see [PLUGIN_STANDARDS.md](PLUGIN_STANDARDS.md)")
+- Plugin documentation must reflect the isolated file convention (never reference legacy shared files)
 
 ### Contributing Plugin Documentation
 

README.md

@@ -1,7 +1,8 @@
 <p align="center">
   <img src="https://img.shields.io/npm/v/superacli" alt="npm">
-  <img src="https://img.shields.io/badge/release-2026--05--14-blue" alt="Latest Release">
+  <img src="https://img.shields.io/badge/release-2026--06--07-blue" alt="Latest Release">
   <img src="https://img.shields.io/badge/license-MIT-green" alt="License">
+  <img src="https://img.shields.io/badge/plugins-5000+-blueviolet" alt="Plugins">
   <img src="https://img.shields.io/github/stars/javimosch/supercli?style=social" alt="Stars">
 </p>
 

docs/plugins-how-to.md

@@ -111,12 +111,16 @@ Every plugin harness consists of:
 
 ### Minimal Plugin Structure
 
+Use the isolated plugin structure described at the top of this guide. Every file
+must live inside `plugins/<name>/` — never at the top level or in shared directories.
+
 ```
-my-plugin/
-├── plugin.json          # Required: manifest
-├── README.md            # Optional: plugin documentation
-└── examples/            # Optional: example usage
-    └── example.sh
+plugins/my-plugin/
+├── plugin.json              # Required: manifest with commands
+├── meta.json                # Required: description, tags, has_learn
+├── install-guidance.json    # Optional: install steps
+├── skills/quickstart/SKILL.md  # Optional: agent guide
+└── README.md                # Optional: human docs
 ```
 
 ## plugin.json Manifest
@@ -157,9 +161,9 @@ The `plugin.json` file is the core of your harness. It describes:
 {
   "name": "beads",              // Unique plugin identifier
   "version": "0.1.0",           // Semantic versioning
-  "description": "...",         // Short description
+  "description": "...",         // Short description (30-150 chars, see PLUGIN_STANDARDS.md)
   "source": "https://...",      // Link to upstream CLI
-  "tags": ["task", "automation"], // Optional: discovery tags
+  "tags": ["task", "automation"], // Optional: discovery tags (3-8 tags, see TAG_VOCABULARY.md)
   "author": "Your Name"         // Optional: plugin author
 }
 ```
@@ -433,8 +437,10 @@ Once your plugin is tested and working:
 2. **Structure it properly**:
    ```
    my-plugin-harness/
-   ├── plugin.json
-   ├── meta.json
+   ├── plugin.json              # Required: manifest with commands
+   ├── meta.json                # Required: description, tags, has_learn
+   ├── install-guidance.json    # Optional: install steps
+   ├── skills/quickstart/SKILL.md  # Optional: agent guide
    ├── README.md
    ├── LICENSE
    └── examples/