tool.json

{
  "name": "charactercheck",
  "family_class": "verdict",
  "version": "0.8.0",
  "status": "released",
  "distribution": {
    "source": "This manifest describes CharacterCheck 0.8.0.",
    "published": "Pin charactercheck==0.8.0 and verify the public artifact and trust-bearing output.",
    "version_warning": "Source metadata is not artifact provenance; verify the installed version and distribution attestations."
  },
  "description": "Read-only compilation of selected D&D Beyond character fields into mechanical context, canonical assessments, provenance, findings, and versioned snapshots.",
  "boundary": "Not complete rules validation, encounter/world/session state, role enforcement, or proof of action legality. No mutations are exposed.",
  "install": "Pin charactercheck==0.8.0; from a trusted clone, python3 -m charactercheck runs without runtime dependencies",
  "example": "python3 -m charactercheck derive examples/sample-character.json --brief",
  "commands": {
    "charactercheck derive <ref> [--brief]": "selected derivation plus canonical fields, findings, trust, and observation metadata",
    "charactercheck derive <ref> --table-evaluation": "value-free deterministic self-attested table.evaluation/1.0 assessment envelope; also accepted by report",
    "charactercheck stance <ref>": "stance envelope with canonical assessment, findings, trust, and observation metadata",
    "charactercheck qa <ref> [--full]": "100-question Coverage Inventory pairing answers with closed states; not validity",
    "charactercheck report <ref> [--brief]": "canonical fields/trust plus findings and identified feature names",
    "charactercheck snapshot <ref>": "export CharacterSnapshotV1 with separate default-mechanical, stored-character, and whole-envelope hashes plus omission coverage",
    "charactercheck diff <ref> --baseline <snapshot.json>": "classify supported changes; distinct snapshots with any omitted-source coverage or restriction semantics fail closed as indeterminate at $",
    "charactercheck quiz <ref>": "settlement and sheet-specific finding questions with conservative expected values",
    "charactercheck seatpack <ref> [--for-dm] [--include-persona]": "privacy-minimized read-only context; --for-dm marks all player-authority live values; persona is local explicit opt-in",
    "charactercheck intake <ref> [--for-dm] [--include-persona]": "pre-session context, questions, trust and authority boundary; --for-dm is redaction, not authorization",
    "charactercheck selftest": "offline installation and selected-derivation smoke test",
    "charactercheck doctor [ref] [--json]": "redacted runtime/network/source diagnosis",
    "charactercheck --schema": "machine-readable CLI contract"
  },
  "input": {
    "accepted": [
      "positive 1-20 digit numeric id with no leading zero",
      "exact HTTPS dndbeyond.com/characters/<id>",
      "direct regular local JSON file where enabled",
      "CharacterSnapshotV1"
    ],
    "limits": "Raw local/remote character payloads: 8 MiB. Local CharacterSnapshotV1 envelopes: 16 MiB. MCP request lines: 8 MiB. All JSON also has bounded depth, nodes, strings, collections, inventory, modifiers, and container traversal."
  },
  "exit_codes": {
    "0": "command succeeded with no command-specific finding/change status",
    "1": "derive/report lint-only, diff named change or indeterminate comparison, or selftest failure",
    "2": "unsupported content is present; inspect field states before use",
    "3": "usage error: the call itself was malformed. Fix the call and retry; never route this to a human. Family-wide code, FAMILY.md v2.2",
    "4": "input, retrieval, validation, or internal failure; read the action field"
  },
  "command_exit_contracts": {
    "derive/report": "0 no lint/unhandled; 1 lint with no unhandled; 2 one or more unhandled records; 4 structured failure",
    "diff": "0 complete comparison with no detected change; 1 any named change or indeterminate omitted-source/restriction comparison; 4 structured failure",
    "stance/qa/snapshot/quiz/seatpack/intake": "0 when emitted even if fields/findings require attention; 4 structured failure",
    "selftest": "0 pass; 1 fail",
    "doctor": "0 all checks pass; 4 otherwise",
    "usage": "argparse errors are plain text and exit 3; unsupported command-specific flag combinations are structured and exit 3"
  },
  "privacy": {
    "default": "mechanical; account identifiers, linked images, appearance, notes, and persona omitted",
    "persona": "explicit authorized local CLI/library opt-in only (--include-persona in the CLI); bounded and marked untrusted",
    "mcp": "no persona opt-in and no host-local file access",
    "consent": "public sharing does not imply model transfer, persistence, training, recurring tests, or publication"
  },
  "snapshot": {
    "normalized_data_hash": "canonical hash of the default privacy-filtered mechanical character; used as source_revision and excludes persona and omitted fields",
    "snapshot_character_hash": "canonical hash of the exact filtered character stored in the snapshot; includes persona only after explicit local opt-in",
    "snapshot_id": "hash of the complete envelope except its own value",
    "observed_at": "canonical UTC RFC 3339 observation metadata; not a trusted or attested timestamp",
    "authenticity": "unkeyed hashes are integrity/content identifiers only; they are not signatures, source attestations, trusted timestamps, or authorization evidence",
    "coverage": {
      "unclassified_top_level_omitted": "boolean only; no omitted name or value is serialized",
      "unclassified_nested_omitted": "boolean only; no omitted name or value is serialized",
      "semantic_values_omitted": "boolean only; fixed field-owned semantic-gap codes route the impact without serializing omitted text",
      "scoped_mechanical_omissions": "sorted canonical family names only; reviewed omitted source field names and values are not serialized"
    },
    "derive_invariant": "the same typed coverage appears under meta.source_coverage; reviewed display/provenance omissions are trust-neutral, scoped mechanical omissions add source:scoped-fields-omitted for listed families, either unclassified-field flag adds source:unclassified-fields-omitted and routes every mechanical family to unknown, and semantic-value omissions retain fixed gap codes that route known root-item impact to unsupported and unscoped non-item or nested-item impact to global unknown",
    "diff_invariant": "distinct snapshots with any nonempty omission coverage or omitted modifier restriction semantics emit $ in unsupported_changes and relationship indeterminate; same-revision named non-mechanical deltas are mechanically_unchanged; exact identity is unchanged"
  },
  "library": {
    "canonical": "package-level derive(ref), stance(ref), and project_table_evaluation(report) preserve trust and source coverage",
    "plain_fetch": "fetch(ref) raises source_coverage when returning a plain character would discard omission metadata",
    "raw_workspace": "build is not package-exported; engine.build also raises source_coverage on incomplete raw sources"
  },
  "shared_evaluation": {
    "schema_version": "table.evaluation/1.0",
    "authority_status": "self_attested",
    "privacy": "field states, authority labels, bounded evidence codes, and source/policy digests only; no character values",
    "mutable_state": "player-authority mutable fields are out-of-scope advisories requiring player/session-host reconciliation",
    "exit_codes": "0 checked_clean; 1 complete with advisories/findings; 2 incomplete, unsupported, invalid, or internal_error",
    "boundary": "pre-session character context only; not source authentication, freshness, encounter/session authority, or action legality"
  },
  "mcp": {
    "command": "charactercheck-mcp",
    "transport": "stdio",
    "protocol_version": "2025-11-25",
    "request_limit_bytes": 8388608,
    "response_limit_bytes": 4194304,
    "tools": [
      "derive",
      "stance",
      "qa",
      "diff",
      "snapshot",
      "seatpack",
      "quiz",
      "report",
      "intake",
      "selftest",
      "doctor"
    ],
    "result_contract": "generic bounded text plus the tool object in structuredContent",
    "capabilities": "read-only public remote refs; no host-local files, persona opt-in, authenticated principal, role enforcement, or mutation"
  },
  "trust": {
    "trusted": "no detected finding within supported coverage; not a global safety claim",
    "ask_player": "known ambiguity requires the supplied human question",
    "unsupported": "observed content has no applicable handler for that family",
    "unknown": "observed content has unknown target scope; derived families fail closed",
    "invalid": "known content is malformed or contradictory and the value must be declined",
    "canonical_field_states": [
      "trusted",
      "confirm",
      "unsupported",
      "unknown",
      "invalid",
      "not_applicable"
    ],
    "precedence": "invalid > unknown > unsupported > confirm > trusted; not_applicable is orthogonal",
    "field_record": "value/state/formula/inputs/sources/rules_profile/findings/confidence/authority/as_of/stale/sensitivity",
    "autonomous_ready": false
  },
  "errors": {
    "contract": "recognized runtime/input failures use safe structured error/message/action/retryable/exit_code with refs, paths, values, and raw detail omitted; argparse usage errors remain plain text",
    "kinds": [
      "bad_flag",
      "not_public",
      "not_found",
      "bad_ref",
      "network",
      "rate_limited",
      "bad_json",
      "upstream",
      "missing_file",
      "local_files_disabled",
      "file_read",
      "file_policy",
      "invalid_character",
      "input_too_large",
      "input_too_deep",
      "input_limit",
      "cyclic_reference",
      "persona_requires_local",
      "snapshot_schema",
      "snapshot_integrity",
      "snapshot_required",
      "snapshot_source_mismatch",
      "source_coverage",
      "output_too_large",
      "internal_error"
    ]
  }
}