superacli 1.1.6 → 1.1.8

package/CONTRIBUTING.md

@@ -0,0 +1,270 @@
+# Contributing to supercli
+
+Welcome to supercli! We're excited that you're interested in contributing. This guide will help you understand how to contribute effectively.
+
+## Introduction
+
+supercli is a universal capability router that bridges humans and AI agents to multiple CLI tools, APIs, MCP servers, and workflows. We welcome contributions in many forms:
+
+- **Code improvements** - Bug fixes, new features, performance improvements
+- **Documentation** - Improving guides, examples, and API references
+- **Plugin development** - Creating new harnesses for CLI tools
+- **Issue reporting** - Helping us identify and reproduce problems
+- **Community support** - Answering questions and helping others
+
+## Getting Started
+
+### Prerequisites
+
+Before contributing, ensure you have:
+
+- [Node.js](https://nodejs.org/) (LTS version recommended)
+- [npm](https://www.npmjs.com/) or [pnpm](https://pnpm.io/)
+- Git for version control
+- Any CLI tools you want to create plugins for
+
+### Setting Up Your Development Environment
+
+```bash
+# Fork the repository on GitHub
+# Clone your fork
+git clone https://github.com/YOUR_USERNAME/supercli.git
+cd supercli
+
+# Install dependencies
+npm install
+
+# Copy environment configuration
+cp .env.example .env
+
+# Run tests to verify setup
+npm test
+```
+
+### Finding Things to Work On
+
+- Check the [Issues](https://github.com/javimosch/supercli/issues) for bugs and feature requests
+- Look for issues tagged with `good first issue` for beginner-friendly contributions
+- Review the [Project Board](https://github.com/javimosch/supercli/projects) for planned work
+- Propose new features by opening a discussion
+
+## Issue Reporting
+
+### Bug Reports
+
+When reporting bugs, include:
+
+1. **Clear title** describing the issue
+2. **Steps to reproduce** - Be specific and detailed
+3. **Expected vs actual behavior** - What you expected vs what happened
+4. **Environment details** - OS, Node.js version, supercli version
+5. **Relevant logs** - Error messages, stack traces
+6. **Minimal reproduction** - If possible, a small code snippet that reproduces the issue
+
+### Feature Requests
+
+For new features:
+
+1. **Describe the feature** - What should happen and why it's useful
+2. **Use cases** - Who benefits and how they'll use it
+3. **Alternatives considered** - What other approaches did you consider?
+4. **Implementation suggestions** - If you have ideas, share them
+
+### Issue Template Example
+
+```markdown
+## Description
+[A clear description of the issue or feature request]
+
+## Steps to Reproduce (for bugs)
+1. Run '...'
+2. Execute '...'
+3. See error
+
+## Expected Behavior
+[What you expected to happen]
+
+## Actual Behavior
+[What actually happened]
+
+## Environment
+- OS: [e.g., macOS 14.0]
+- Node.js: [e.g., v20.10.0]
+- supercli: [e.g., v1.2.3]
+
+## Additional Context
+[Any other relevant information, logs, or screenshots]
+```
+
+## Code Contributions
+
+### Branching Strategy
+
+- `main` - Stable release branch
+- `feature/*` - New features
+- `fix/*` - Bug fixes
+- `docs/*` - Documentation improvements
+
+### Development Workflow
+
+```bash
+# Create a feature branch
+git checkout -b feature/my-new-feature
+
+# Make your changes
+# Write tests for new functionality
+
+# Run tests before committing
+npm test
+
+# Commit with clear messages
+git commit -m "feat: add support for new CLI tool X"
+
+# Push and create PR
+git push origin feature/my-new-feature
+```
+
+### Commit Message Conventions
+
+We follow [Conventional Commits](https://www.conventionalcommits.org/):
+
+```
+<type>(<scope>): <description>
+
+[optional body]
+
+[optional footer]
+```
+
+**Types:**
+- `feat` - New feature
+- `fix` - Bug fix
+- `docs` - Documentation changes
+- `style` - Code style (formatting, no logic change)
+- `refactor` - Code refactoring
+- `test` - Adding or updating tests
+- `chore` - Maintenance tasks
+
+**Examples:**
+```
+feat(plugins): add support for new CLI wrapper
+fix(docker): resolve container listing timeout
+docs(readme): update installation instructions
+```
+
+### Pull Request Process
+
+1. **Ensure tests pass** - Run `npm test` locally
+2. **Update documentation** - If adding features, update relevant docs
+3. **Follow code style** - Use existing patterns in the codebase
+4. **Write meaningful PR description** - Explain what and why
+5. **Respond to feedback** - Be responsive to review comments
+
+### Code Review Guidelines
+
+**For reviewers:**
+- Review code for correctness, not style (let linters handle formatting)
+- Test the changes locally when possible
+- Provide constructive, actionable feedback
+- Focus on the code, not the person
+
+**For contributors:**
+- Keep PRs focused and reasonably sized
+- Respond to feedback promptly
+- Ask for clarification if feedback is unclear
+
+## Documentation Contributions
+
+### Where to Find Documentation
+
+- `/docs/` - Main documentation directory
+- `/docs/plugins-how-to.md` - Plugin development guide
+- `/docs/skills/` - Skill system documentation
+- `/README.md` - Project overview and quick start
+- 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
+
+### Contributing Plugin Documentation
+
+When creating or updating plugins:
+
+1. Add a `README.md` in the plugin directory
+2. Include installation instructions
+3. Document available commands
+4. Provide usage examples
+5. Reference the upstream CLI documentation
+
+## Plugin Development
+
+### Want to Create a New Plugin?
+
+See our detailed [Plugin Harness Development Guide](docs/plugins-how-to.md) for:
+
+- Plugin manifest structure (`plugin.json`)
+- Command wrapping vs passthrough patterns
+- Argument mapping configuration
+- Testing and debugging tips
+
+### Quick Plugin Checklist
+
+Before submitting a plugin for inclusion:
+
+- [ ] Plugin has a valid `plugin.json` manifest
+- [ ] Binary dependency checks are configured
+- [ ] Commands have clear descriptions
+- [ ] JSON output is supported where applicable
+- [ ] Plugin README includes installation and usage instructions
+- [ ] Tests pass (if applicable)
+- [ ] No hardcoded credentials or secrets
+
+### Publishing Plugins
+
+Once your plugin is ready:
+
+```bash
+# Install locally for testing
+supercli plugins install ./path/to/my-plugin
+
+# Test functionality
+supercli my-plugin --help
+
+# Publish to community registry
+supercli plugins publish ./my-plugin
+```
+
+## Community Guidelines
+
+### Code of Conduct
+
+We are committed to providing a welcoming, inclusive environment. By participating, you agree to:
+
+- Be respectful and inclusive
+- Welcome newcomers and help others learn
+- Accept constructive criticism professionally
+- Focus on what's best for the community
+
+### Getting Help
+
+- **Discussions** - Use GitHub Discussions for questions
+- **Issues** - For bugs and feature requests
+- **Documentation** - Check docs/ before asking
+
+### Supporting Others
+
+- Answer questions in discussions
+- Help newcomers get started
+- Share your experience and knowledge
+
+## License
+
+By contributing to supercli, you agree that your contributions will be licensed under the [MIT License](LICENSE).
+
+---
+
+Thank you for contributing to supercli! Your help makes this project better for everyone.

package/README.md

@@ -1,6 +1,36 @@
-# supercli — Universal Skill Router for AI Agents
+# supercli — Universal Capability Router for AI Agents
 
-Discover and execute skills across CLIs, APIs, MCP servers, workflows, and custom automations through a single agent-friendly interface.
+Discover and execute capabilities across CLIs, APIs, MCP servers, workflows, and custom automations through a single agent-friendly interface.
+
+## Why Supercli?
+
+### For Humans
+Stop context-switching between CLI tools. supercli gives you one consistent interface to AWS, GitHub, Docker, Kubernetes, and 50+ other platforms—so you spend less time learning syntax and more time solving problems.
+
+### For AI Agents
+Access a standardized skill graph where every capability follows predictable input/output envelopes. Discover, compose, and execute workflows with machine-readable metadata that enables reliable automation.
+
+### For Supervisors
+Trust that your AI agents have explicit boundaries. Every skill declares its capabilities, inputs, outputs, and safety profile—no hidden behavior. Agents must explicitly opt-in to raw CLI power via passthrough, and every invocation follows predictable error patterns.
+
+### Shared Value
+
+| Scenario | Direct CLI Approach | Supercli Approach |
+|----------|-------------------|-------------------|
+| Learning a new tool | Read 50-page docs, memorize flags | `supercli skills get <tool>.*` with examples |
+| Cross-tool workflows | Manual context passing between commands | Automatic context propagation |
+| Finding capabilities | Google/search multiple docs sites | `supercli skills search <query>` |
+| Safe automation | Risk of accidental destructive commands | Agent-friendly wrappers with safeguards |
+| Writing scripts | Parse inconsistent text output | Consistent JSON envelopes |
+
+**Same command structure everywhere:** `supercli <plugin> <action> ...`
+
+Whether you're human or agent, supercli reduces cognitive load through consistent skill invocation patterns while maintaining access to full CLI power via passthrough (`supercli <plugin> -- <raw-args>`).
+
+## Terminology
+
+- **Capability**: Any executable unit exposed by Supercli (command, OpenAPI operation, MCP tool binding, HTTP integration, workflow step).
+- **Skill document**: Agent-facing guidance in `SKILL.md` format, indexed by the `skills` catalog commands.
 
 ## BIN Aliases
 
@@ -10,44 +40,44 @@ Discover and execute skills across CLIs, APIs, MCP servers, workflows, and custo
 - superacli (What was available) (Super Agent/ic CLI)
 - sc (For lazy people)
 
-## What Is a Skill Layer?
+## What Is a Capability Layer?
 
-Everything the system exposes becomes a **skill**:
+Everything the system exposes becomes a **capability**:
 
 | Source | Turns into |
 | --- | --- |
-| CLI command | Skill |
-| OpenAPI endpoint | Skill |
-| MCP tool | Skill |
-| HTTP request | Skill |
-| Workflow / plan step | Skill |
+| CLI command | Capability |
+| OpenAPI endpoint | Capability |
+| MCP tool | Capability |
+| HTTP request | Capability |
+| Workflow / plan step | Capability |
 
-Agents query the skill layer once, and supercli handles discovery, routing, and execution across every connected ecosystem. Skills are addressable (e.g., `beads.issue.list` or `docker.container.ps`), searchable, and consistently described so agents never need bespoke integrations per tool.
+Agents query the capability layer once, and supercli handles discovery, routing, and execution across every connected ecosystem. Capabilities are addressable (e.g., `beads.issue.list` or `docker.container.ps`), searchable, and consistently described so agents never need bespoke integrations per tool.
 
 ### Core Responsibilities
 
-1. **Discovery** – build a real-time catalog of skills across bundled harnesses, adapters, and plugins.
-2. **Routing** – resolve the right execution adapter (CLI, HTTP, MCP, custom runtime) from an incoming skill ID.
+1. **Discovery** – build a real-time catalog of capabilities across bundled harnesses, adapters, and plugins.
+2. **Routing** – resolve the right execution adapter (CLI, HTTP, MCP, custom runtime) from an incoming capability ID.
 3. **Execution** – normalize inputs/outputs, enforce envelopes, and surface deterministic status codes.
-4. **Extension** – let teams add new skills by dropping in manifests, OpenAPI specs, or plugin harnesses.
+4. **Extension** – let teams add new capabilities by dropping in manifests, OpenAPI specs, or plugin harnesses.
 
-Example skill executions:
+Example capability executions:
 
 ```bash
-supercli beads issue list              # Calls beads skill adapter
+supercli beads issue list              # Calls beads capability adapter
 supercli gwc drive files list          # Calls Google Workspace adapter
 supercli docker container ps           # Calls Docker plugin (when installed)
 ```
 
-## Skill Sources
+## Capability Sources
 
-supercli generates skills from six primary channels:
+supercli generates capabilities from six primary channels:
 
 - **Bundled Harnesses** – beads (tasks/issues), gwc (Google Workspace), commiat (commit automation)
 - **Built-in Adapters** – OpenAPI specs, raw HTTP integrations, MCP (Model Context Protocol) servers
 - **Plugin Harnesses** – community or internal CLIs installed via `supercli plugins install`
-- **AI & Plans** – natural-language `ask` commands create execution DAGs composed of skills
-- **Workflows** – repeatable plans and stored executions referenced as skills
+- **AI & Plans** – natural-language `ask` commands create execution DAGs composed of capabilities
+- **Workflows** – repeatable plans and stored executions referenced as capabilities
 - **Future Extensions** – popular CLIs such as gh, aws, docker, kubectl, terraform, etc.
 
 ## Architecture
@@ -57,9 +87,9 @@ supercli generates skills from six primary channels:
                   │
             supercli runtime
                   │
-            Skill Discovery Layer
+          Capability Discovery Layer
                   │
-             Skill Router Core
+           Capability Router Core
                   │
    ┌──────────────┼──────────────┬───────────────┐
    │              │              │               │
@@ -67,61 +97,92 @@ supercli generates skills from six primary channels:
 ```
 
 The router intelligently:
-- **Discovers** available skills from every adapter and caches metadata for fast lookup
+- **Discovers** available capabilities from every adapter and caches metadata for fast lookup
 - **Routes** commands to the correct harness based on namespace and capability metadata
 - **Executes** with unified error handling, envelopes, and output formatting
-- **Surfaces** machine-readable descriptions so agents can plan against the skill graph
+- **Surfaces** machine-readable descriptions so agents can plan against the capability graph
 
-## Why Skills Matter
+## Why Capabilities Matter
 
-Traditional CLIs force agents to learn tool-specific syntax. supercli replaces that effort with a discoverable skill graph so agents can:
+Traditional CLIs force agents to learn tool-specific syntax. supercli replaces that effort with a discoverable capability graph so agents can:
 
 - Search (`supercli skills search "database"`) to find relevant capabilities instantly
 - Inspect (`supercli skills get beads.issue.create`) to pull schema-rich metadata
-- Compose (`supercli plan …`) to build DAGs out of skills without writing glue code
+- Compose (`supercli plan …`) to build DAGs out of capabilities without writing glue code
 - Delegate execution to the same router regardless of whether the source is a CLI, API, or MCP tool
 
-## Skill Mesh Vision
+### Safety & Trust for Agents
+
+**Why supervisors can trust supercli with AI agents:**
 
-supercli is steadily evolving toward a broader **skill mesh** that provides discovery, routing, execution, composition, and governance across every tool in the stack. Near-term focus areas include:
+- **Explicit Boundaries:** Each skill declares its capabilities, inputs, and outputs—nothing hidden
+- **Consistent Wrappers:** Agent-friendly modes (`--json`, `--silent`) prevent interactive prompts
+- **Audit Trail:** Every invocation logs plugin, action, inputs, and outputs
+- **Opt-In Power:** Full CLI access requires explicit passthrough (`supercli <plugin> -- <raw-args>`)
+- **Predictable Errors:** Standardized error envelopes with machine-readable codes
+- **No Side Effects:** Skills declare whether they're read-only or state-modifying
 
-- **Deeper skill registry** with richer metadata, tagging, and policy controls
-- **Graph-native discovery** so agents can traverse related skills and capability clusters
-- **Execution DAG observability** for multi-skill plans with retries and status streaming
+**Agent workflow example:**
+
+```bash
+# 1. Find relevant capabilities
+supercli skills search "deployment" --json
+
+# 2. Inspect exact requirements
+supercli skills get aws.cfn.deploy --json
+
+# 3. Execute with predictable output
+supercli aws cfn deploy --stack-name my-stack --template-file template.yaml --json
+```
+
+## Capability Mesh Vision
+
+supercli is steadily evolving toward a broader **capability mesh** that provides discovery, routing, execution, composition, and governance across every tool in the stack. Near-term focus areas include:
+
+- **Deeper capability registry** with richer metadata, tagging, and policy controls
+- **Graph-native discovery** so agents can traverse related capabilities and capability clusters
+- **Execution DAG observability** for multi-capability plans with retries and status streaming
 - **Agent endpoints** that expose the router over HTTP/webhooks for direct agent access beyond the CLI
 
 These directional goals keep the README aligned with the system’s trajectory without overpromising unshipped features.
 
+## Operating Modes
+
+Supercli supports two runtime modes:
+
+| Mode | What it means | Best for |
+| --- | --- | --- |
+| Local-only (default) | CLI runs directly from local config/cache and installed plugins. No Supercli server required. | Personal workflows, offline/local development, quick setup |
+| Server mode | A Supercli server hosts shared config/plugins via API; clients connect with `SUPERCLI_SERVER` and run `supercli sync`. | Team-shared capabilities/plugins, centralized governance, multi-client consistency |
+
+Notes:
+- `supercli sync` is only relevant when `SUPERCLI_SERVER` is configured.
+- Local plugins still take precedence over server-synced plugins when names collide.
+- Server plugin behavior and policies are documented in [docs/features/server-plugins.md](docs/features/server-plugins.md).
+
 ## Quick Start
 
 ```bash
-# Quick usage (no install, local-only by default)
+# Path A: Local-only mode (default, no server required)
 npx supercli help                      # List available harnesses
 npx supercli skills teach
 
 # Install
 npm install
 
-# Configure (copy and edit)
+# Optional local config
 cp .env.example .env
 
-# Start server (defaults to local JSON files, no MongoDB required!)
-npm start
-# Or alternatively, start via CLI:
-# supercli --server
-
-# Open Web UI
-open http://localhost:3000
-
-# CLI usage - Multi-harness routing
+# === Human Perspective ===
+# Local CLI usage - Multi-harness routing
 supercli help                          # List all harnesses
-supercli beads                         # List beads skills
-supercli gwc                           # List Google Workspace skills
+supercli beads                         # List beads capabilities
+supercli gwc                           # List Google Workspace capabilities
 supercli beads issue list              # Execute beads command
 supercli gwc drive files list          # Execute Google Workspace command
 
-# Skills discovery across harnesses
-supercli skills list                   # All skills from all harnesses
+# Capabilities discovery across harnesses
+supercli skills list                   # Capability docs from all harnesses
 supercli skills search "database"      # Full-text search across harnesses
 
 # AI-driven multi-harness execution
@@ -131,6 +192,32 @@ supercli ask "show my tasks and recent commits"
 supercli plugins list
 supercli plugins explore               # Browse available plugins
 supercli plugins install commiat       # Install community plugin
+
+# === Agent Perspective ===
+# Programmatic capability discovery (machine-readable)
+supercli --help-json                   # Full capability manifest in JSON
+supercli skills list --json           # All skills with metadata
+supercli skills search "deployment" --json  # Filtered capabilities
+
+# Predictable execution with JSON output
+supercli aws sts get-caller-identity --json
+supercli gh issue list --json
+
+# Inspect specific capabilities before execution
+supercli skills get aws.cfn.deploy --json
+
+# Path B: Server mode (optional, shared backend)
+# Start server (local JSON storage by default; MongoDB optional)
+npm start
+# Or alternatively, start via CLI:
+# supercli --server
+
+# Point CLI clients to the server, then sync shared config/plugins
+export SUPERCLI_SERVER=http://localhost:3000
+supercli sync
+
+# Open Web UI
+open http://localhost:3000
 ```
 
 ## CLI Usage
@@ -139,8 +226,8 @@ supercli plugins install commiat       # Install community plugin
 
 ```bash
 # Basic harness routing
-supercli <harness>                          # List skills in harness
-supercli <harness> <skill-group> <action>   # Execute skill
+supercli <harness>                          # List capabilities in harness
+supercli <harness> <capability-group> <action>   # Execute capability
 
 # Examples across different harnesses
 supercli beads issue create --title "Fix bug"
@@ -150,13 +237,13 @@ supercli commiat validate --commit-msg "my message"
 
 # Discovery
 supercli help                              # List all harnesses
-supercli skills list                       # List all skills from all harnesses
+supercli skills list                       # List capability docs from all harnesses
 supercli skills search --harness beads     # Search within harness
 supercli skills search "database"          # Full-text search across harnesses
 
 # Inspection
 supercli inspect beads issue create        # Command details + schema
-supercli skills get beads.issue.create     # Get skill metadata
+supercli skills get beads.issue.create     # Get capability documentation
 
 # Execution
 supercli beads issue create --title "New task"      # Standard execution
@@ -172,9 +259,9 @@ export OPENAI_BASE_URL=https://api.openai.com/v1   # Enable AI resolution
 supercli ask "list my tasks and summarize them"     # Execute across harnesses
 
 # Config & Server
-supercli sync                              # Sync local cache from server
+supercli sync                              # Server mode only: sync cache from SUPERCLI_SERVER
 supercli config show                       # Show cache info
-supercli --server                          # Start backend server
+supercli --server                          # Start backend server (server mode)
 
 # Plugin Harness Management
 supercli plugins list                      # List installed harnesses
@@ -221,7 +308,7 @@ supercli --help-json                       # Machine-readable capabilities
 A **plugin harness** bridges dcli to an external CLI tool. Each plugin:
 - Defines a manifest (`plugin.json`) with available commands
 - Maps CLI arguments to dcli's command structure
-- Supports command wrapping, passthrough, remote skills catalogs, or any combination of those patterns
+- Supports command wrapping, passthrough, remote skill-document catalogs, or any combination of those patterns
 - Includes dependency checks and installation guidance
 
 ### Currently Supported Harnesses
@@ -299,7 +386,7 @@ The dcli community is actively developing plugins for popular CLIs:
 - **Monitoring**: datadog, prometheus CLIs
 - Many others based on community requests
 
-Want to contribute a plugin harness? [See plugin guide](docs/plugin-harness-guide.md) and submit to the registry!
+Want to contribute? See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines on contributing code, documentation, and plugin harnesses.
 
 ## Output Envelope