tool.json

{
  "name": "inkcheck",
  "version": "0.7.2",
  "description": "Mechanical QA for ink interactive-fiction stories — compile checks, bounded systematic branch exploration, runtime-error repro paths, and dead-content review. Writes no prose.",
  "homepage": "https://github.com/chaoz23/inkcheck",
  "license": "MIT",
  "install": {
    "npx": "npx -y inkcheck <story.ink>",
    "npm": "npm install -g inkcheck"
  },
  "interfaces": [
    "cli",
    "mcp"
  ],
  "cli": {
    "command": "inkcheck",
    "usage": "inkcheck <story.ink> [options]",
    "machineOutput": "--json",
    "flags": [
      {
        "flag": "capabilities [--json]",
        "description": "Report versioned schemas, limits, search modes, and explicit supported/unavailable features without requiring a story."
      },
      {
        "flag": "inspect <story.ink> [--json]",
        "description": "Return a deterministic bounded source-only project map without compiling or exploring."
      },
      {
        "flag": "validate-config [inkcheck.yml] [--json]",
        "description": "Validate project configuration schema v1 and resolve its project-local entrypoint."
      },
      {
        "flag": "init [directory] [--entrypoint story.ink] [--json]",
        "description": "Create an idempotent minimal inkcheck.yml without overwriting existing project files."
      },
      {
        "flag": "agent-kit --format codex [directory] [--entrypoint story.ink] [--json]",
        "description": "Scaffold config, pinned CI, artifact ignore rules, and compact version-matched Codex instructions after a no-overwrite preflight."
      },
      {
        "flag": "checkpoints list|show <checkpoint-id> [--json]",
        "description": "List source-bound local base-shared checkpoints or inspect bounded freshness metadata without printing the frontier payload."
      },
      {
        "flag": "artifacts findings|finding|replay <report-id> [<finding-id>] [--limit N] [--cursor C] [--json]",
        "description": "Page through privacy-minimal saved-finding summaries, fetch one full stable finding, or replay one current indexed witness. Pages default to 20 and cap at 100; replay rejects stale or path-changed source."
      },
      {
        "flag": "artifacts delete <report-id> | artifacts prune --keep N [--apply] [--json]",
        "description": "Preview explicit report cleanup, then apply the same deterministic selection with --apply. Prune keeps N newest reports per entrypoint and selects at most 100 per invocation; no save silently deletes evidence."
      },
      {
        "flag": "resume <checkpoint-id> --max-states <n> [--json]",
        "description": "Resume an exact current base-shared checkpoint to a larger total state grant and save the next generation when work remains. CLI only."
      },
      {
        "flag": "--json",
        "description": "Emit the full report as a single JSON object on stdout. Use this for programmatic consumption."
      },
      {
        "flag": "--human",
        "description": "Emit a prioritized human-readable fix list grouped by severity, with file/line locations and choice paths where available."
      },
      {
        "flag": "--markdown",
        "description": "Emit a GitHub Step Summary-friendly Markdown report."
      },
      {
        "flag": "--strict",
        "description": "Also fail on warnings, unvisited knots, truncation, or external stubs (exit 1)."
      },
      {
        "flag": "--max-depth <n>",
        "description": "Max choices deep to explore, from 1 to 1000. Default 100."
      },
      {
        "flag": "--max-states <n>",
        "description": "Total exploration state budget across the complementary DFS portfolio, diversity-first beam slice, seeded random-sampling slice, and repro-shortening slice, from 1 to 100000000. Default 10000000. The memory guard (85% of the V8 heap by default) stops cleanly before OOM, so the practical limiter on a big run is memory, not this ceiling; small stories early-exit on exhaustive coverage."
      },
      {
        "flag": "--seed <n>",
        "description": "Seed for the reproducible random-sampling slice, from 1 to 4294967295. Default 1; the same seed always samples the same walks."
      },
      {
        "flag": "--search <mode>",
        "description": "Select portfolio (default), shared, or shared-variable. Variable-aware mode dedicates 12.5% of shared-frontier selections to uncommon observed variable states and transitions."
      },
      {
        "flag": "--concurrency <auto|n>",
        "description": "Workload-aware auto activation is the local portfolio default with a four-lane ceiling. Explicit 1 opts out; 2-16 fixes the worker ceiling. Reports expose the deterministic pilot decision and actual resource-bounded concurrency."
      },
      {
        "flag": "--max-memory <mb>",
        "description": "Stop exploration cleanly before heap use exceeds <mb> and return a partial report (truncatedBy.memory), instead of crashing on an uncatchable V8 out-of-memory. Default: 85% of the V8 heap limit (honors --max-old-space-size)."
      },
      {
        "flag": "--max-time <s>",
        "description": "Stop exploration cleanly after <s> seconds and return a partial report (truncatedBy.time), instead of running to the state budget. Default: no time limit. Useful for CI or hosted runs that need a bounded wall clock but still want the findings so far."
      },
      {
        "flag": "--profile",
        "description": "Print a static story-shape profile (variables, choice density, longest divert path) plus the depth limit and pass weights inkcheck would choose, without exploring. Combine with --json for machine-readable output."
      },
      {
        "flag": "--auto",
        "description": "Apply the shape profile: raise --max-depth when static divert paths outrun the default (explicit flags always win; limits are never lowered) and use the profile's pass weights for the portfolio."
      },
      {
        "flag": "--next",
        "description": "After the check, apply the report's nextRun recommendation and rerun automatically — up to 3 escalations, stopping on a stop/investigate verdict, at the flag ceilings, or when an escalated run finds nothing new. The per-run trail appears in --json output as `runs`; hop narration goes to stderr."
      },
      {
        "flag": "--no-min-repro",
        "description": "Skip the small BFS repro-shortening slice and spend that budget on the DFS portfolio instead."
      },
      {
        "flag": "--save-checkpoint",
        "description": "Persist an unfinished exact frontier. Requires --search=shared --no-min-repro without assertions, goals, --auto, --next, or --save-report."
      }
    ],
    "exitCodes": {
      "0": "Clean — compiled and explored with no errors (and, under --strict, no warnings, unvisited knots, truncation, or external stubs).",
      "1": "Failure — compile errors, runtime errors, or (under --strict) warnings, unvisited knots, truncation, or external stubs.",
      "2": "Usage error — no story file given or bad arguments."
    },
    "jsonSchema": {
      "reportEnvelope": "{ schemaVersion: 1, inkcheckVersion, storyFingerprint: {algorithm, source, value}, effectiveConfiguration, bindingLimit, compile, stats?, profile?, explore?, nextRun?, runs?, checkpoint?: {saved, id?, path?, pruned?, resumedFrom?, reason?} }",
      "capabilities": "{ schemaVersion, inkcheckVersion, schemas: {report, config, projectInspection, artifact, checkpointArtifact, searchSession, regressionArtifact, campaignPolicy}, limits: {..., defaultMcpSessionWindowStates, maxMcpSessionWindowStates, maxMcpSessionTotalStates, maxMcpSessionFiles, maxMcpSessionEvents, maxMcpCampaignWindows, maxRegressionPinBytes, maxRegressionPinsPerProject}, searchModes, resumableSearchSurfaces, features: {projectInspection, indexedWitnesses, assertions, goals, localReportArtifacts, savedFindingLookup, resumableSearch, interactiveSearchSessions, campaignResultWindows, sessionWitnessReplay, sessionRegressionPins} }",
      "searchSession": "{ schemaVersion, inkcheckVersion, sessionCapability?: bearer-secret, session: {revision, status, recoverable, totalGranted, statesExplored, latestReportId, latestCheckpointId?, bindingLimit, findings, events, droppedEventCount}, campaign?: {campaignId, intent, status, stopReason, spend, ceilings, unusedStates, windows, disclosure, latestWindow?}, savedFindings, nextOperation }",
      "regressionPin": "private runtime-only artifact with stable pin ID, session/entrypoint binding, indexed choices, story seed, baseline fingerprint, and hashed expected runtime errors; check returns fixed|still_failing|path_changed without search states",
      "savedFindings": "{ artifact: {id, entrypoint, freshness}, findings: [{id, kind, section, hasWitness, hasReplay, sourceLocation?}], page: {limit, returned, total, nextCursor} }; fetch returns one summary plus complete finding; replay returns summary plus playtest result",
      "artifactLifecycle": "{ operation: 'delete'|'prune', applied, keepPerEntrypoint?, candidateCount, selectedCount, remainingCandidates, bytes, candidates: [{id, path, entrypoint, createdAt, sizeBytes}] }",
      "inspection": "{ schemaVersion, inkcheckVersion, entrypoint, includes, shape, semantics, externals, knots, variables, truncation, recommendedNextOperation }",
      "compile": "{ success: bool, issues: [{severity, file, line, message}], errors: int, warnings: int, todos: int }",
      "stats": "{ words, knots, stitches, functions, choices, gathers, diverts }",
      "explore": "{ statesExplored: int, endingsFound: [{id, kind, path, choiceIndices, firstDiscoveredAtState, replay, witness, finalText, variables, foundBy?}], runtimeErrors: [{id, kind, message, path, choiceIndices, firstDiscoveredAtState, replay, witness, sourceLocation?, foundBy?}], assertionResults: [{id, description?, when, status: 'violated'|'not_observed'|'exhaustively_verified', observations, violations: [{id, kind: 'assertion.violation', observedValues, path, choiceIndices, replay, witness, sourceLocation?, foundBy}]}], unvisitedKnots: [{name, file, line, inboundDiverts?, staticOrphanCandidate?}], externalFunctionsStubbed: string[], randomnessDetected: bool, truncated: bool, truncatedBy: {maxDepth: bool, maxStates: bool, beamWidth: bool, frontier: bool, memory: bool, time: bool, worker?: bool}, exhaustive: bool, limits: {maxDepth, maxStates, seed?}, execution?: {mode, requestedConcurrency, effectiveConcurrency, fallbackReason?, workers: [{pass, granted, consumed, status, error?}]}, schedule?: [{round: int, entries: [{pass, granted, consumed, newEndings, newKnots, newRuntimeErrors}]}], passes?: [{pass, systematic, statesExplored, granted, endingsFound, runtimeErrorsFound, knotsVisited, newEndings, newKnots, newRuntimeErrors, dedupeHits, maxDepthReached, lastDiscoveryAtState, truncatedBy, exhaustive, peakFrontier?, prunes?, uniqueStates?, peakPendingStates?, peakPendingBytes?, variableStatesObserved?, variableTransitionsObserved?, rareVariableTransitions?}] }",
      "profile": "(with --auto or --profile --json) { knots, functions, variables, varAssignments, earlyAssignmentShare, choiceLines, hasCycles, longestKnotPath, choiceDepthEstimate, suggested: {maxDepth, weights: {last, first, insideOut, beam, random}, rationale: string[]} }",
      "nextRun": "{ recommendation: 'stop'|'deepen'|'broaden'|'reseed'|'investigate', stop: bool, flags: {maxDepth, maxStates, seed?}, rationale: string, expectedGain: string } — deterministic function of the report; loop on it: rerun with flags until stop is true",
      "runs": "(with --next) [{run: int, flags, statesExplored, endings, runtimeErrors, visitedKnots, recommendation}]"
    }
  },
  "mcp": {
    "defaultProfile": "compact",
    "fullProfileEnvironment": {
      "INKCHECK_MCP_PROFILE": "full"
    },
    "command": "npx",
    "args": [
      "-y",
      "inkcheck",
      "mcp"
    ],
    "config": {
      "mcpServers": {
        "inkcheck": {
          "command": "npx",
          "args": [
            "-y",
            "inkcheck",
            "mcp"
          ]
        }
      }
    },
    "tools": [
      {
        "name": "inkcheck_capabilities",
        "description": "Versioned schemas, limits, search modes, and explicit feature availability."
      },
      {
        "name": "inspect_story",
        "description": "Bounded source-only project map; does not compile or explore."
      },
      {
        "name": "compile_story",
        "description": "Structured compile issues (severity, file, line)."
      },
      {
        "name": "start_search",
        "description": "Start one synchronous durable base-shared result window; returns a bearer capability and exact checkpoint when work remains."
      },
      {
        "name": "inkcheck_workflow",
        "description": "Route post-discovery search, campaign, finding, replay, regression, assertion, goal, cancellation, and playtest operations through one compact schema."
      }
    ],
    "fullProfileTools": [
      "story_stats",
      "playtest_story",
      "explore_story",
      "start_campaign",
      "continue_campaign",
      "open_report",
      "get_finding",
      "inspect_search",
      "continue_search",
      "add_goal",
      "add_assertions",
      "cancel_search",
      "replay_witness",
      "pin_regression",
      "check_regression"
    ]
  },
  "agentLoop": "inkcheck_capabilities -> inspect_story -> compile_story -> start_search -> use inkcheck_workflow for inspect/finding/replay/regression/campaign operations -> edit -> compile_story -> verify through the same source/config/seed contract. The default compact profile has five tools; INKCHECK_MCP_PROFILE=full restores separate compatibility tools. Campaigns remain one shared trajectory in this version; add_goal starts from the story root and never replaces exact base-search work. Never infer that a truncated, randomized, externally driven, knee-stopped, or campaign-bounded story was completely verified."
}