feat: make providers optional with --provider flag and fix sh/MCP bugs (#39, #37, #41)

scripts/build-web.ts

@@ -19,9 +19,9 @@ async function buildWeb() {
   }
 
   // Step 0: Read logo assets
-  const DOCS_PUBLIC = join(ROOT, 'capa-docs', 'public');
-  const faviconSvgPath = join(DOCS_PUBLIC, 'favicon.svg');
-  const logoPngPath = join(DOCS_PUBLIC, 'favicon-white.png');
+  const ASSETS = join(ROOT, 'assets');
+  const faviconSvgPath = join(ASSETS, 'favicon.svg');
+  const logoPngPath = join(ASSETS, 'favicon-white.png');
 
   let faviconDataUrl = '';
   let logoPngDataUrl = '';

skills/capabilities-manager/SKILL.md

@@ -23,19 +23,26 @@ Use this skill when:
 - User needs to configure security (blocked phrases, character sanitization)
 - User wants to manage AGENTS.md or CLAUDE.md content (the `agents` section)
 - User wants to run tools from the command line or explore available tools with `capa sh`
+- User needs to define provider-specific rules (Cursor rules, Copilot rules, etc.)
+- User wants to add remote plugins that bundle skills, servers, and tools
+- User needs to configure sub-agents with scoped tools and instructions
+- User wants to manage the remote source cache or bypass it
 
 ## Core Concepts
 
 ### Capabilities File
 
-The `capabilities.yaml` (or `capabilities.json`) file defines everything an agent can do. It has six main sections:
+The `capabilities.yaml` (or `capabilities.json`) file defines everything an agent can do. It has these main sections:
 
-1. **providers**: MCP clients where skills are installed (e.g. `cursor`, `claude-code`)
+1. **providers** (optional): MCP clients where skills are installed (e.g. `cursor`, `claude-code`). When omitted, `capa install` resolves providers via `--provider` flag, DB memory, or interactive prompt.
 2. **options**: Tool exposure (`toolExposure`), security (`security`), CLI prerequisites (`requiresCommands`)
 3. **skills**: Modular knowledge packages (when/how to use tools)
 4. **servers**: MCP servers (local subprocess or remote HTTP)
 5. **tools**: Executable capabilities (MCP or shell commands)
 6. **agents**: (Optional) Manages `AGENTS.md` / `CLAUDE.md` content in the project root
+7. **subagents**: (Optional) Named sub-agent configurations with filtered tool access
+8. **rules**: (Optional) Provider rules installed into each provider's rules directory or instructions file
+9. **plugins**: (Optional) Remote plugin packages that bundle skills, servers, and tools
 
 ### Skills vs Tools
 
@@ -59,20 +66,27 @@ Only properties that are present are applied. If a blocked phrase is detected du
 | Command | Purpose |
 |--------|--------|
 | `capa init [--format json\|yaml]` | Create a new capabilities file |
-| `capa install [-e [file]]` | Install skills, agents, register servers; prompt for credentials (use `-e` for .env) |
+| `capa install [-e [file]] [-p <id>] [--no-cache]` | Install skills, agents, rules, register servers; prompt for credentials |
 | `capa add <source> [--id <id>]` | Add a skill (GitHub, GitLab, remote URL, local path, or `--installed`) |
-| `capa clean` | Remove CAPA-installed skills and agent blocks |
+| `capa clean` | Remove CAPA-installed skills, rules, and agent blocks |
 | `capa sh [group] [subcommand] [--arg value]` | List or run tools; unknown commands pass through to the OS shell |
 | `capa start \| stop \| restart \| status` | Manage the CAPA server |
+| `capa auth [provider]` | Authenticate with Git providers (github.com, gitlab.com, etc.) |
+| `capa upgrade` | Upgrade capa to the latest version |
+| `capa cache` | Show cache stats; `capa cache clean` to wipe |
 
 **Full command reference**: See `references/commands.md`.
 
 ## Capabilities File Structure (Summary)
 
+- **Providers**: Optional. When omitted, resolved at install time via `--provider` flag → DB memory → interactive prompt.
 - **Skills**: Six types — `inline`, `github`, `gitlab`, `remote`, `local`, `installed`. Each has `id`, `type`, `def` (and for inline, `content`; for others, `repo`/`url`/`path` plus optional `requires`, `description`).
 - **Servers**: `type: mcp` with `def.cmd`/`args`/`env` (local) or `def.url`/`headers` (remote). Optional `tlsSkipVerify: true`, `description`.
 - **Tools**: `type: mcp` (def: `server`, `tool`, optional `defaults`) or `type: command` (def: `run.cmd`/`args`, optional `init`, `group`, `description`).
 - **Agents**: Optional `base` (ref or type+def) and `additional` list (inline, remote, github, gitlab snippets). Managed files: `AGENTS.md` always; `CLAUDE.md` when a Claude provider is present.
+- **Subagents**: Named sub-agent configurations with filtered tool access, per-provider MCP endpoints and agent files.
+- **Rules**: Types `inline`, `remote`, `github`, `gitlab`. Each has `id`, optional `providers`, `appliesTo` (glob), `alwaysApply`, `description`. Installed as files (Cursor `.cursor/rules/`) or folded into instructions files.
+- **Plugins**: Remote packages (`type: remote`, `def.uri`) that bundle skills, servers, and tools from a provider manifest.
 
 **Full schema and YAML examples**: See `references/capabilities-schema.md`.
 
@@ -105,8 +119,8 @@ for using the `capa` CLI directly from the terminal.
 
 | Topic | File |
 |-------|------|
-| Commands (init, install, add, clean, sh, server) | `references/commands.md` |
-| Capabilities schema (skills, servers, tools, security, agents) | `references/capabilities-schema.md` |
+| Commands (init, install, add, clean, sh, server, auth, upgrade, cache) | `references/commands.md` |
+| Capabilities schema (skills, servers, tools, rules, plugins, security, agents, subagents) | `references/capabilities-schema.md` |
 | Workflows and full examples | `references/workflows-and-examples.md` |
 | Troubleshooting | `references/troubleshooting.md` |
 

skills/capabilities-manager/references/capabilities-schema.md

@@ -1,10 +1,12 @@
 # Capabilities File Schema
 
-Full reference for `capabilities.yaml` / `capabilities.json` structure: basic layout, skills (all six types), servers, tools, security, `requiresCommands`, and the `agents` section.
+Full reference for `capabilities.yaml` / `capabilities.json` structure: basic layout, skills (all six types), servers, tools, rules, plugins, security, `requiresCommands`, the `agents` section, and sub-agents.
 
 ## Basic Structure (YAML)
 
 ```yaml
+# providers is optional — when omitted, resolved at install time via
+# --provider flag, DB memory from a previous install, or interactive prompt.
 providers:
   - cursor
   - claude-code
@@ -31,7 +33,11 @@ tools:
     type: mcp|command
     def: { ... }
 
-# subagents: [ { id, description?, skills, tools, instructions?, agents? } ]
+# rules: [ { id, type, content?, url?, def?, providers?, appliesTo?, alwaysApply?, description? } ]
+
+# plugins: [ { type: remote, def: { uri } } ]
+
+# subagents: [ { id, description?, skills, tools, instructions? } ]
 ```
 
 ## Skills Section (six types)
@@ -120,4 +126,73 @@ subagents:
 
 **Cleanup:** On each `capa install`, sub-agents removed from the config are automatically unregistered and their agent files removed. `capa clean` removes all sub-agent registrations.
 
-For full YAML examples of every skill type, server type, security block, requiresCommands, tool defaults/group, and agents schema, see the original capability file docs or the examples in `references/workflows-and-examples.md`.
+## Rules Section
+
+Defines rules installed into each provider's rules directory or instructions file.
+
+- **Providers with a rules directory** (e.g. Cursor → `.cursor/rules/`): each rule is written as a separate file with optional YAML frontmatter (`description`, `globs`, `alwaysApply`).
+- **Providers without a rules directory** (e.g. Claude Code, Codex): rule content is folded into the provider's instructions file as a capa marker block.
+
+**Fields:**
+- `id` (required): Unique identifier, used as filename stem and capa marker id.
+- `type` (required): `inline`, `remote`, `github`, or `gitlab`.
+- `providers` (optional): Restrict this rule to specific providers. When omitted, applies to all.
+- `appliesTo` (optional): Glob patterns for auto-attached rules (maps to Cursor `globs`).
+- `alwaysApply` (optional): When `true`, the rule is always loaded regardless of file context.
+- `description` (optional): Human-readable description used in frontmatter.
+- `content` (inline only): Literal rule content.
+- `url` (remote only): Raw URL to fetch.
+- `def.repo` (github/gitlab only): Repository + file path (same format as skills).
+
+```yaml
+rules:
+  - id: code-style
+    type: inline
+    alwaysApply: true
+    description: Project code style guidelines
+    content: |
+      Use TypeScript strict mode. Prefer const over let.
+      Always use explicit return types on exported functions.
+
+  - id: test-patterns
+    type: inline
+    appliesTo:
+      - "**/*.test.ts"
+      - "**/*.spec.ts"
+    description: Testing conventions
+    content: |
+      Use describe/it blocks. Prefer toBe over toEqual for primitives.
+
+  - id: shared-rules
+    type: github
+    def:
+      repo: my-org/standards@rules/typescript.md
+    providers:
+      - cursor
+```
+
+`capa clean` removes all capa-installed rules. Rules can be scoped per-provider and support the same source types as skills.
+
+## Plugins Section
+
+Remote plugin packages that bundle skills, servers, and tools from a provider manifest.
+
+**Fields:**
+- `id` (optional): Stable identifier; derived from name + ref if absent.
+- `type` (required): `remote`.
+- `def.uri` (required): Plugin URI. Format: `github:owner/repo`, `github:owner/repo:v1.0.0`, or `github:owner/repo#sha`. GitLab URIs also supported (`gitlab:...`).
+
+```yaml
+plugins:
+  - type: remote
+    def:
+      uri: github:some-org/my-plugin:v1.0.0
+
+  - type: remote
+    def:
+      uri: github:another-org/tools-bundle#abc123
+```
+
+Plugins are resolved during `capa install`. The plugin manifest is fetched from the repository and its skills, servers, and tools are merged into the capabilities. Plugin-sourced items are tagged with `sourcePlugin` attribution for display.
+
+For full YAML examples of every skill type, server type, security block, requiresCommands, tool defaults/group, rules, plugins, and agents schema, see the original capability file docs or the examples in `references/workflows-and-examples.md`.

skills/capabilities-manager/references/commands.md

@@ -2,7 +2,7 @@
 
 ## Contents
 
-- Initialize Capabilities · Install Capabilities · Add Skills · Clean Managed Files · Shell / Tool Executor · Server Management
+- Initialize Capabilities · Install Capabilities · Add Skills · Clean Managed Files · Shell / Tool Executor · Server Management · Authentication · Upgrade · Cache Management
 
 ---
 
@@ -24,15 +24,19 @@ Creates a new capabilities file with default configuration. Defaults to YAML for
 capa install
 capa install -e             # Load variables from .env file
 capa install -e .prod.env   # Load variables from custom env file
-capa install --env          # Alternative syntax for -e
+capa install -p cursor      # Install for a single provider
+capa install --no-cache     # Bypass on-disk cache; re-resolve all remote sources
 ```
 
 Reads the capabilities file and:
-1. Installs all skills to configured MCP clients (creates skill directories in `.cursor/skills/` and/or `~/Library/Application Support/Claude/skills/`)
-2. Installs/updates `AGENTS.md` (always) and `CLAUDE.md` (when `claude-code` is in providers) if the `agents` section is present (downloads base file, upserts/prunes snippets)
-3. Configures the CAPA server with your tools and servers
-4. Prompts for any required credentials via web UI (unless `-e` flag is used)
-5. Registers the project's MCP endpoint in client config files
+1. Resolves providers (from the file, `--provider` flag, DB memory, or interactive prompt)
+2. Installs all skills to configured MCP clients (creates skill directories in `.cursor/skills/` and/or `~/Library/Application Support/Claude/skills/`)
+3. Installs/updates `AGENTS.md` (always) and `CLAUDE.md` (when `claude-code` is in providers) if the `agents` section is present (downloads base file, upserts/prunes snippets)
+4. Installs rules into each provider's rules directory or instructions file if the `rules` section is present
+5. Resolves plugins and merges their skills, servers, and tools
+6. Configures the CAPA server with your tools and servers
+7. Prompts for any required credentials via web UI (unless `-e` flag is used)
+8. Registers the project's MCP endpoint in client config files (skipped when no tools or subagents are configured)
 
 **Security**: If `options.security` is configured with `blockedPhrases` or `allowedCharacters`, the corresponding checks run during installation. Omit or comment out each property to disable it. If a blocked phrase is found, installation stops immediately and reports which skill and phrase caused the block. When `allowedCharacters` is present, character sanitization runs: the baseline (printable ASCII + standard whitespace) is always preserved, and the value specifies extra Unicode ranges to keep on top of that.
 
@@ -42,6 +46,14 @@ Reads the capabilities file and:
   - With filename: Uses the specified file (e.g., `.prod.env`, `.staging.env`)
   - The env file must exist, or the command will fail with an error
   - All required variables must be present in the env file
+- `-p, --provider <id>`: Install for a single provider (e.g. `cursor`, `claude-code`). Overrides the `providers` field in the capabilities file.
+- `--no-cache`: Bypass the on-disk cache and lockfile; re-resolve every remote source (skills, agents, rules, plugins) from scratch.
+
+**Provider resolution** (when `providers` is omitted from the capabilities file):
+1. `--provider` flag (highest priority)
+2. `providers` array in the capabilities file
+3. Stored providers from a previous install (persisted in DB)
+4. Interactive prompt (TTY only — auto-detects installed providers)
 
 **When to use**: After modifying the capabilities file or adding new skills.
 
@@ -124,9 +136,49 @@ capa sh gitlab list-merge-requests --help   # Show argument details
 
 ```bash
 capa start              # Start the CAPA server (background)
+capa start -f           # Start in foreground (for debugging)
 capa stop               # Stop the CAPA server
 capa restart            # Restart the CAPA server
 capa status             # Check server health and uptime
 ```
 
 **When to use**: Managing the background MCP server that handles tool execution and credential management.
+
+---
+
+## Authentication
+
+```bash
+capa auth               # Authenticate with the default Git provider
+capa auth github.com    # Authenticate with GitHub
+capa auth gitlab.com    # Authenticate with GitLab
+```
+
+Authenticates with Git providers for accessing private repositories (skills, plugins, agent snippets). Credentials are stored securely in the capa database.
+
+**When to use**: When you need to access private GitHub or GitLab repositories for skills or plugins.
+
+---
+
+## Upgrade
+
+```bash
+capa upgrade
+```
+
+Upgrades capa to the latest published version.
+
+**When to use**: When a new version of capa is available (capa will notify you after commands when an update is available).
+
+---
+
+## Cache Management
+
+```bash
+capa cache              # Show cache stats (location, size, per-repo breakdown)
+capa cache clean        # Remove all cached repositories and snapshots
+```
+
+Capa caches remote sources (GitHub/GitLab repositories) locally to speed up subsequent installs. The cache stores bare git mirrors and file snapshots. Use `capa cache clean` to free disk space, or `capa install --no-cache` to bypass the cache for a single install without clearing it.
+
+**When to use**: Inspecting cache disk usage or clearing stale cached data.

skills/capabilities-manager/references/troubleshooting.md

@@ -69,7 +69,7 @@ If a server that uses Bearer token auth (e.g. Databricks, a self-hosted GitLab M
 
 - Ensure the `Authorization` header is present in `def.headers` — CAPA skips the OAuth2 probe for these servers automatically
 - Verify the token stored for `${VarName}` is valid for the specific server URL (wrong-workspace tokens are a common cause of 403 errors)
-- Re-set the token with `capa vars set VarName <new-token>` or re-run `capa install -e` with an updated `.env` file
+- Re-set the token by re-running `capa install -e` with an updated `.env` file, or update it via the web UI during `capa install`
 
 ### Tool Not Found Errors
 
@@ -78,3 +78,49 @@ If a server that uses Bearer token auth (e.g. Databricks, a self-hosted GitLab M
 - Check that server ID in tool definition uses `@` prefix (e.g., `@server-id`)
 - Ensure MCP server is running: check `capa status`
 - Verify tool name matches the actual tool provided by the MCP server
+
+### Provider Not Found / Interactive Prompt Required
+
+When `providers` is omitted from the capabilities file and no `--provider` flag is passed:
+
+- **In a TTY**: capa shows an interactive prompt to select a provider
+- **In CI/non-TTY**: fails with an error. Fix: pass `--provider <id>` explicitly
+
+```bash
+# CI-safe: always pass --provider
+capa install -p cursor
+
+# See all supported providers
+capa install -p invalid-name  # error message lists all valid provider IDs
+```
+
+Once a provider is selected, it's stored in the DB and reused on subsequent installs.
+
+### Stale Cache / Outdated Remote Sources
+
+If skills, rules, or plugins from remote repositories aren't updating:
+
+```bash
+# Bypass cache for one install
+capa install --no-cache
+
+# Or wipe the full cache
+capa cache clean
+capa install
+```
+
+### Rules Not Appearing
+
+- Verify the `rules` section is present in `capabilities.yaml`
+- For Cursor: rules are written to `.cursor/rules/{id}.mdc` — check that directory
+- For Claude Code/Codex: rules are folded into the instructions file (e.g. `CLAUDE.md`)
+- If `providers` field is restricted on a rule, ensure your active provider matches
+- Run `capa clean` then `capa install` to force a full reinstall
+
+### MCP Server Not Registered (No Tools Configured)
+
+If `capa install` does not register the MCP server in `.cursor/mcp.json` or equivalent:
+
+- This is expected when no tools or subagents are configured in the capabilities file
+- Add at least one tool or subagent to trigger MCP server registration
+- If the server was previously registered but tools were removed, capa automatically unregisters it