GW-033: Add onboarding, verdict, security, data, eval, and MCP docs

[trippyogi]

Outcome

Complete the documentation set required for public beta: onboarding, verdict semantics, agent workflow, CLI, MCP, security, local data, capture, evaluation, troubleshooting, and compatibility guidance.

A new user should be able to install Gitworthy, connect it to an MCP host, run a bounded hunt, interpret every verdict and limitation, record an outcome, and recover from common failures without maintainer assistance.

Progress already delivered

PR #63 completed a meaningful first slice:

• Agent-first README and product positioning.
• Cursor, ChatGPT, Hermes, and generic MCP onboarding.
• Correct scout versus execute model.
• hunt as bounded per-candidate preflight rather than one global verdict.
• ACT-as-queue semantics and mandatory recheck before implementation.
• docs/AGENT_WORKFLOW.md with host-agent responsibilities, tool selection, ranking, dispositions, contribution paths, and outcome workflow.

Keep this issue open for the remaining beta documentation below.

Why this matters

Gitworthy's safety model depends on users and agents understanding what was checked, what was not checked, and what each next action permits. Missing or stale docs can turn a correct VERIFY result into an unsafe implementation decision.

Scope

• Installation and clean-environment quickstart.
• MCP setup and troubleshooting for Cursor plus at least two other hosts/harnesses.
• CLI reference and practical examples aligned with GW-030.
• MCP tool reference aligned with GW-032.
• Verdict, disposition, evidence-strength, checked/not-checked, partial-run, and retry semantics.
• Scout/execute workflow and contribution-path matrix.
• Configuration/profile/target-manifest reference.
• Local store, outcomes, capture, export, migration, rebuild, retention, and privacy guidance.
• Frozen/live/private evaluation architecture and report interpretation.
• Security model, hostile-input assumptions, token scope, redaction, and private disclosure.
• Troubleshooting for auth scopes, rate limits, timeline visibility, npm/git failures, corrupt local data, stale decisions, and MCP stdio.
• Compatibility/deprecation policy and version pinning guidance.
• Contributor onboarding and calibration-case workflow.

Non-goals

• No marketing claims not supported by released behavior.
• No hosted SaaS documentation before such a product exists.
• No duplicate hand-maintained command contract when generated reference can be used.
• No instructions that encourage parsing human CLI output.

Dependencies and readiness

• Depends on GW-030 / issue GW-030: Complete human CLI renderer, strict help, quiet/verbose/progress #39.
• Depends on GW-032 / issue GW-032: Complete MCP descriptions, annotations, structured results, and errors #41.
• Contributor readiness: PARTIALLY BLOCKED. PR Reframe README around agent-first preflight #63 established the structure and agent workflow. Remaining command/tool reference should land after GW-030: Complete human CLI renderer, strict help, quiet/verbose/progress #39 and GW-032: Complete MCP descriptions, annotations, structured results, and errors #41 stabilize.

Acceptance criteria

• Fresh user can install and complete doctor, check, and hunt from documented steps.
• MCP setup is verified against Cursor and at least two additional hosts/harnesses.
• Every primary CLI command and MCP tool links to accurate inputs, outputs, examples, and failure behavior.
• ACT, VERIFY, SKIP, dispositions, evidence strength, and recheck rules are explained consistently.
• Local data/capture/eval/security docs match actual schemas and defaults.
• Troubleshooting includes actionable remediation for every doctor capability warning/failure.
• Docs distinguish current behavior, beta limitations, and post-1.0 ideas.
• All internal links and command examples are checked in CI.
• README remains concise and routes deep reference into docs/.

Tests and validation

• Documentation link and command-snippet checks.
• Clean-container onboarding walkthrough from packed npm package.
• MCP setup smoke tests for supported examples.
• Review against CLI help, generated schemas, and MCP tool metadata.
• Security/privacy review of token, capture, and data instructions.
• First-user usability review before closing.

Likely documentation map

• README.md: product story and fast onboarding.
• docs/AGENT_WORKFLOW.md: scout/execute policy.
• docs/CLI.md and docs/MCP.md: reference and examples.
• docs/VERDICTS.md: decision semantics.
• docs/CONFIG.md: profiles and target manifests.
• docs/DATA.md: runs, decisions, outcomes, captures, migrations.
• docs/EVALS.md: suites, adjudication, and reports.
• docs/SECURITY_MODEL.md: hostile-input and credential boundaries.
• docs/TROUBLESHOOTING.md: doctor-driven remediation.

Compatibility

Documentation is part of the 1.0 contract. Examples should pin versions where reproducibility matters and must be updated in the same PR as any public command/tool/schema change.

[trippyogi]

Docs set shipped in #77. Remaining: first-user walkthrough validation and host harness verification.