docs: document the integration contract and trust model

[AbhiramDwivedi]

Closes #56

What

Documentation only. Adds two README sections so other tools can integrate against SkillSpector reliably:

• Integrating SkillSpector — exit codes, the JSON output shape, the severity/recommendation enums + band mapping, and a recommended install-gate mapping (SAFE→allow, CAUTION→ask, DO_NOT_INSTALL→block).
• Trust model and data egress — no execution of scanned code; LLM analysis sends file contents unless --no-llm; SC4 sends dependency names to OSV.dev by design; defense-in-depth, not a sandbox.

Cross-linked from docs/DEVELOPMENT.md.

Stacked on #50 — please review/merge that first. This PR will then show only its own delta.

Test

No code changes.

🤖 Generated with Claude Code

[rng1995]

Review: APPROVE

Documentation-only, and a genuinely valuable addition — a stable integration contract plus an honest trust/egress model is exactly what downstream install-gates and CI integrations need. I cross-checked the documented contract against the current source rather than taking it on faith, and it holds up:

• Per-issue JSON shape matches Finding.to_dict(): id (from rule_id), category, severity, confidence, and location.{file,start_line,end_line} are all real keys. Documenting these as the stable subset and telling integrators to treat the remaining emitted fields (pattern, finding, explanation, remediation, code_snippet, intent, …) as best-effort is the right forward-compatible framing.
• Severity → recommendation mapping matches the code exactly: LOW→SAFE, MEDIUM→CAUTION, HIGH/CRITICAL→DO_NOT_INSTALL.
• Exit codes are internally consistent with the risk bands: DO_NOT_INSTALL begins at the HIGH band (score ≥ 51), i.e. score > 50, which is precisely the CLI's exit 1 threshold; SAFE/CAUTION (score ≤ 50) map to exit 0; errors to 2. The note steering integrators to read recommendation rather than relying on the collapsed exit code is good advice.

Trust model / data egress — this section is the highlight. Clearly stating that scanned code is never executed, that LLM analysis sends file contents to the configured provider (with --no-llm to opt out), that the supply-chain check sends dependency coordinates to a third-party API even under --no-llm, and that the tool is defense-in-depth rather than a host sandbox is responsible, non-misleading security documentation. No over-promising.

Open-source hygiene — clean. No internal hostnames, tickets, or infra details; the stacked changes also swap internal-tracker-style TODO comments for generic roadmap notes, which is good for a public repo.

Minor / optional (non-blocking)

• As noted in the description, this is stacked on the docs-status PR, so the current diff includes that PR's changes too; merging the base first will reduce this to just the README delta.
• The --no-llm egress caveat is well placed; if the local-CLI provider work lands, a one-line follow-up clarifying that "configured provider" can be a local agent CLI (file contents still leave the static path, but stay on the machine) would round it out. Not needed for this PR.

Verified and accurate. Approving.