docs: Clarify CLI-wrapper-only architecture

[beonde]

Summary

This PR clarifies that capiscio-node is a CLI wrapper only - it does not expose a TypeScript/JavaScript API for programmatic validation.

Changes

Documentation Updates

• Rewrote index.md - Clearly states this is a CLI wrapper, not an SDK
• Deleted architecture.md - Removed outdated TypeScript API documentation
• Created cli.md - Complete CLI reference with all flags verified from capiscio-core source
• Updated programmatic-usage.md - Shows how to spawn CLI as child process (the only supported method)
• Updated scoring.md - Focused on CLI JSON output parsing
• Removed api.md references - A2AValidator is exported but untested/unsupported
• Updated mkdocs.yml - Simplified nav structure

Key Clarification

⚠️ CLI Wrapper Only - This package wraps the capiscio-core binary. For programmatic validation in Node.js, spawn the CLI as a child process.

What This Means for Users

• npm install -g capiscio → Use capiscio validate from terminal
• No TypeScript API → Spawn CLI if you need programmatic access
• All 28 CLI flags → Documented and verified against Go source

Files Changed

• docs/index.md - Rewrote to clarify wrapper nature
• docs/reference/cli.md - New complete CLI reference
• docs/reference/architecture.md - Deleted
• docs/reference/api.md - Cleared (A2AValidator unsupported)
• docs/guides/programmatic-usage.md - Child process approach
• docs/guides/scoring.md - CLI JSON parsing
• mkdocs.yml - Simplified nav

[Copilot]

Pull request overview

This PR restructures the documentation to clarify that the capiscio npm package is a CLI wrapper only for the Go-based capiscio-core binary, not a native TypeScript/JavaScript SDK. The changes remove outdated API documentation and focus on CLI usage with programmatic access via child process spawning.

Key changes:

• Simplified documentation structure removing architecture and process docs
• New comprehensive CLI reference with all flags and examples
• Updated programmatic usage guide to demonstrate spawning CLI as child process
• Clarified scoring guide to focus on parsing CLI JSON output

Reviewed changes

Copilot reviewed 10 out of 10 changed files in this pull request and generated 11 comments.

Show a summary per file

File	Description
mkdocs.yml	Updated navigation: removed API Reference and Architecture, added CLI Reference
docs/validation-process.md	Deleted - removed detailed validation process documentation
docs/scoring-system.md	Deleted - removed detailed scoring system documentation
docs/reference/architecture.md	Deleted - removed TypeScript architecture documentation
docs/reference/cli.md	New file - comprehensive CLI reference with all 28 flags and usage examples
docs/reference/api.md	Updated - now describes TypeScript API as available but focuses on CLI wrapper approach
docs/index.md	Rewritten - clearly states this is a CLI wrapper with binary distribution model
docs/guides/scoring.md	Updated - focused on CLI JSON output parsing and CI/CD integration
docs/guides/programmatic-usage.md	Rewritten - demonstrates child process approach instead of TypeScript API

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.