docs: reorganize plugin documentation into structured directories (#505)

Split the large plugins README.md into multiple focused documentation files:

- getting-started/: Overview, quick start, plugin structure
- reference/: Manifest, capabilities, permissions, commands, hooks, events, API, config, CLI
- guides/: Development, best practices, troubleshooting
- examples/: Sample plugin implementations

Added AGENTS.md for AI agent guidelines.

This improves navigation and makes the documentation more maintainable.

Author: echobt

plugins-docs/AGENTS.md

@@ -0,0 +1,146 @@
+# AGENTS.md - Plugin Documentation Guidelines
+
+This file provides guidelines for AI agents working with the Cortex CLI plugin documentation.
+
+## Documentation Structure
+
+```
+plugins-docs/
+├── README.md                    # Main index with links
+├── AGENTS.md                    # This file
+├── getting-started/
+│   ├── overview.md              # Plugin system overview
+│   ├── quick-start.md           # Create first plugin
+│   └── plugin-structure.md      # Directory layout
+├── reference/
+│   ├── manifest.md              # plugin.toml reference
+│   ├── capabilities.md          # Capability types
+│   ├── permissions.md           # Permission types
+│   ├── commands.md              # Custom commands
+│   ├── hooks.md                 # Hook types
+│   ├── events.md                # Event types
+│   ├── api.md                   # Plugin API
+│   ├── configuration.md         # System config
+│   └── cli-commands.md          # CLI usage
+├── guides/
+│   ├── development.md           # Building plugins
+│   ├── best-practices.md        # Security, performance
+│   └── troubleshooting.md       # Common issues
+└── examples/
+    └── README.md                # Example plugins
+```
+
+## Key Concepts
+
+### Plugin System
+
+- Plugins are WASM-based for security and portability
+- Run in isolated sandboxes
+- Must declare capabilities and permissions
+- Can add commands, hooks, and event handlers
+
+### Core Files
+
+- `plugin.toml` - Plugin manifest (required)
+- `plugin.wasm` - Compiled WASM module
+
+### Plugin Locations
+
+1. `~/.cortex/plugins/` - Global plugins
+2. `~/.config/cortex/plugins/` - Config directory
+3. `./.cortex/plugins/` - Project-local
+
+## Documentation Guidelines
+
+### When Adding Documentation
+
+1. **Keep files focused** - One topic per file
+2. **Use consistent headers** - H1 for title, H2 for sections
+3. **Include examples** - Code samples for all features
+4. **Link related docs** - Cross-reference other pages
+5. **Update README.md** - Add new pages to index
+
+### Code Examples
+
+Always provide complete, working examples:
+
+```toml
+# Good: Complete manifest example
+[plugin]
+id = "example"
+name = "Example"
+version = "1.0.0"
+
+capabilities = ["commands"]
+
+[[commands]]
+name = "example"
+description = "Example command"
+```
+
+### Tables
+
+Use tables for reference material:
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `id` | string | ✅ | Unique identifier |
+| `name` | string | ✅ | Display name |
+
+## Common Tasks
+
+### Adding a New Hook Type
+
+1. Document in `reference/hooks.md`
+2. Add to hook types table
+3. Include input/output fields
+4. Provide example
+
+### Adding a New Permission
+
+1. Document in `reference/permissions.md`
+2. Add to permission types section
+3. Include TOML syntax example
+4. Note required capabilities
+
+### Adding a New Event
+
+1. Document in `reference/events.md`
+2. Add JSON example
+3. List event fields
+
+## Related Code
+
+The plugin system implementation is in:
+
+- `cortex-plugins/src/` - Plugin system crate
+- `cortex-plugins/src/manifest.rs` - Manifest parsing
+- `cortex-plugins/src/hooks.rs` - Hook types
+- `cortex-plugins/src/events.rs` - Event types
+- `cortex-plugins/src/api.rs` - Plugin API
+- `cortex-cli/src/plugin_cmd.rs` - CLI commands
+
+## Verification
+
+When updating documentation:
+
+1. Verify code examples compile/work
+2. Check all links are valid
+3. Ensure consistency with implementation
+4. Test CLI commands mentioned
+
+## Style Guide
+
+- Use backticks for `code`, commands, and file names
+- Use **bold** for important terms on first use
+- Use bullet points for lists
+- Keep paragraphs short (3-5 sentences max)
+- Include "Next Steps" sections
+
+## Notes for AI Agents
+
+- The plugin documentation is separate from main AGENTS.md
+- Plugin source is in `cortex-plugins/` crate
+- CLI plugin commands are in `cortex-cli/src/plugin_cmd.rs`
+- Always check implementation matches documentation
+- Update docs when plugin system changes