# Product Contract

This document defines what `sxmc` claims to support today, what should fail
gracefully, and what is intentionally outside the contract.

Use this document together with:

- [USAGE.md](USAGE.md) for the canonical product workflows
- [OPERATIONS.md](OPERATIONS.md) for release and hosting guidance
- [VALIDATION.md](VALIDATION.md) for repeatable release checks and compatibility notes

## Supported And Expected To Work

These are the core product paths we should treat as stable:

### 1. Skills -> MCP

- `sxmc serve` loads skill directories and exposes them over MCP
- per-skill prompts are available when `SKILL.md` is present
- `scripts/` entries become MCP tools
- `references/` entries become MCP resources
- hybrid retrieval tools are always available:
  - `get_available_skills`
  - `get_skill_details`
  - `get_skill_related_file`

### 2. MCP -> CLI

- `sxmc stdio` can discover and invoke tools, prompts, and resources from a stdio MCP server
- `sxmc http` can discover and invoke tools, prompts, and resources from a streamable HTTP MCP server
- `sxmc mcp` can discover and invoke tools, prompts, and resources from baked stdio/http MCP connections
- `sxmc mcp session <server>` supports stateful multi-step workflows against a single baked MCP connection
- `--list`, `--list-tools`, `--list-prompts`, `--list-resources`, `--describe`, and `--describe-tool` are supported CLI surfaces
- one-shot tool execution is supported
- one-shot prompt fetches with `--prompt` are supported
- one-shot resource reads with `--resource` are supported
- baked `server/tool` workflows are supported through `mcp servers|grep|tools|info|call|prompt|read|session`

### 3. API -> CLI

- `sxmc api` auto-detects OpenAPI vs GraphQL
- `sxmc spec` supports direct OpenAPI execution
- `sxmc graphql` supports GraphQL schema-driven invocation

### 4. Hosting And Auth

- local stdio MCP hosting is supported
- remote streamable HTTP MCP hosting at `/mcp` is supported
- `/healthz` is supported for hosted deployments
- bearer-token and required-header auth are supported for remote MCP hosting

### 5. CLI -> AI Startup Surfaces

- `sxmc inspect cli <command>` is supported for deterministic help-based inspection
- `sxmc init ai --from-cli <command> --client <profile>` is supported for generating startup-facing artifacts
- `sxmc init ai --from-cli <command> --coverage full` is supported for generating multi-host startup coverage
- `sxmc scaffold agent-doc --from-profile ...` is supported
- `sxmc scaffold client-config --from-profile ...` is supported
- `sxmc scaffold skill --from-profile ...` is supported
- `sxmc scaffold mcp-wrapper --from-profile ...` is supported
- `sxmc scaffold llms-txt --from-profile ...` is supported as an optional export
- host profiles are supported for:
  - `claude-code`
  - `cursor`
  - `gemini-cli`
  - `github-copilot`
  - `continue-dev`
  - `open-code`
  - `jetbrains-ai-assistant`
  - `junie`
  - `windsurf`
  - `openai-codex`
  - `generic-stdio-mcp`
  - `generic-http-mcp`
- preview, sidecar, patch, and apply modes are supported
- apply mode updates managed markdown blocks or mergeable config files only
- full-coverage apply updates only the explicitly selected `--host` targets and sidecars the rest

## Should Fail Gracefully

These scenarios should not crash the product or produce misleading results:

- promptless/resource-less MCP servers should still allow tool discovery and one-shot tool calls
- zero-argument MCP tools should receive `{}` rather than an omitted argument object
- startup-only invocations like `sxmc --version` and `sxmc --help` should succeed on all supported platforms
- unsupported optional MCP surfaces should be skipped with a clear note rather than failing all discovery
- `scan` should continue to use non-zero exit status for findings by design, but not be treated as a crash
- existing `AGENTS.md` / `CLAUDE.md` files should not be overwritten wholesale by CLI->AI generation
- scaffolded skill and MCP-wrapper files should be created as new files rather than overwriting arbitrary existing files

## Explicitly Outside The Contract

These are not promised as current product behavior:

- persistent multi-turn MCP sessions through repeated fresh `sxmc stdio ...` invocations
- stateful "dialog" continuity across separate CLI invocations without an explicit `sxmc mcp session`
- automated CI launch of proprietary clients like Cursor, Codex, or Claude Code
- universal compatibility with every third-party MCP server without caveats
- benchmark numbers as proof of broad client compatibility
- fully automatic client startup discovery without either a real config file or a real startup-read doc file

## Release Bar

Before a release, we should be able to point to:

1. a passing local certification run
2. a current compatibility matrix
3. a current benchmark snapshot
4. a documented support boundary for anything still out of scope

If a behavior is not covered by one of those, it should not be described as a
guaranteed product path.
