docs: add structured API reference and inline package comments #52

[CoolatMax]

PR Description: API Documentation & Developer Reference

Overview

This PR addresses Issue #52: API - Add API documentation and usage examples. It establishes a comprehensive documentation suite for the sbsh public API, bridging the gap between the Go source code and external developers/integrators.

I have implemented a "Documentation-as-Code" approach by combining structured Markdown guides with standard Go inline package comments.

Changes Made

1. Structured API Reference (docs/api/)

Created a new documentation directory containing specialized guides:

• index.md: High-level architecture and JSON-RPC over Unix Sockets overview.
• terminal-api.md & supervisor-api.md: Detailed "Contract" references for the core controllers, documenting methods like Attach, Resize, and Detach.
• schemas.md: A full breakdown of the TerminalProfile YAML manifest, mapping Go structs to declarative configuration fields.
• examples.md: Practical Go code snippets demonstrating client initialization and session management.

2. Inline Package Documentation

Added standard Go documentation comments to exported interfaces and structs to support go doc and IDE intellisense:

• pkg/api/iface.go: Documented TerminalController and SupervisorController.
• pkg/api/profile.go: Documented YAML manifest structs (ShellSpec, TerminalProfileDoc).
• pkg/supervisor/iface.go: Documented the public Supervisor Client interface.

3. README Integration

Updated the root README.md with a Developer Resources section, providing direct entry points to the new API documentation.

---

Verification Results

• Link Integrity: Verified all cross-links between Markdown files function correctly in the repository browser.
• Go Doc Validation: Confirmed that running go doc ./pkg/api and go doc ./pkg/supervisor correctly outputs the new inline comments.
• Schema Accuracy: Cross-referenced schemas.md with profile.go to ensure JSON/YAML tags match the documentation.

Closes

Closes #52