docs(schema): add field descriptions

[somus]

Pull Request

Summary

• Add JSON Schema description annotations to v0.1.0 and draft field definitions.
• Add a schema-description coverage check to keep public property schemas documented.

Related Issue

• None.

Public Impact

• No public contract change
• Spec or schema change
• Public package API change
• CLI behavior change
• Public URL or docs behavior change

Impact description:

• Annotation-only schema change. Wire format, validation semantics, fixtures, and normative prose are unchanged.

Verification

• node scripts/check-schema-descriptions.mjs - passed
• jq empty schema/draft.json schema/v0.1.0.json - passed
• Annotation-only comparison after stripping description keys from old/new schemas - passed
• mise run check - passed with non-fatal mise cache write warnings outside the workspace

Reviewer Notes

• Review description wording for public schema field comments.
• schema/draft.json and schema/v0.1.0.json are byte-equivalent after this change.

---

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 78998ae7-2c3c-4f0a-a12f-aa3833b84a4b

📥 Commits

Reviewing files that changed from the base of the PR and between 1255aa2 and 8f3edd0.

📒 Files selected for processing (4)

• mise.toml
• schema/draft.json
• schema/v0.1.0.json
• scripts/check-schema-descriptions.mjs

---

📝 Walkthrough

Summary by CodeRabbit

• Documentation

  • Enhanced JSON Schema definitions with comprehensive descriptions across event payloads, metadata fields, and payload structures for improved clarity and consistency.

• Tests

  • Added validation checks to ensure schema documentation standards are maintained.

Walkthrough

This PR enriches JSON Schema definitions for Agent Trail v0.1.0 with comprehensive human-readable descriptions across data structures, event payloads, and discriminator fields. A new validation script ensures property descriptions remain complete as the schema evolves, integrated into the build task automation.

Changes

Schema documentation and validation

Layer / File(s)	Summary
Validation script and task integration scripts/check-schema-descriptions.mjs, mise.toml	A new validator traverses schema/draft.json, collects JSON-pointer paths to properties missing description fields, filters constraint-only duplicates, and exits with error if gaps are found. The script is wired into the check:schema task.
Common data structures documentation schema/draft.json, schema/v0.1.0.json	Segment, taskPlanItem, taskPlanDelta, vcs, sourceMetadata, semanticMetadata, agentMessageUsage, and attachment definitions gain field-level descriptions covering sequencing, hashing, VCS metadata, token usage, and media handling.
Envelope, header, and entry base documentation schema/draft.json, schema/v0.1.0.json	trailEnvelope, header, and entryBase receive extensive descriptions for envelope identity, timestamps, session UIDs, streaming state, agent metadata, fork/redaction tracking, and core event fields.
Message and task plan event documentation schema/draft.json, schema/v0.1.0.json	user_message, agent_message, and task_plan_update events gain descriptions for message text, model information, stop reason, token usage, and attachments.
Tool call and result event documentation schema/draft.json, schema/v0.1.0.json	tool_call variants (file_read, file_write, file_edit, file_patch, file_list, file_search, shell_command, shell_output, shell_input, mcp_call, web_fetch, web_search, tool_search, notebook_edit, subagent_invoke, other) receive descriptions for arguments. tool_result gains descriptions for overflow references, error handling, attachments, and structured meta outputs (MCP blocks, file ranges, shell command results). tool_call_aborted gains descriptions for scope, target IDs, and blocking information.
Query and response event documentation schema/draft.json, schema/v0.1.0.json	user_query events gain descriptions for question items, headers, multi-select flags, secret handling, and answer options. user_query_response gains descriptions for answer selections and custom responses.
System, thinking, and model change event documentation schema/draft.json, schema/v0.1.0.json	system_event, agent_thinking, user_interrupt, context_compact, branch_point, branch_summary, model_change, mode_change, and thinking_level_change events gain descriptions for payload text/data, change reasons, trigger sources, and turn associations.
Session termination and finalization event documentation schema/draft.json, schema/v0.1.0.json	session_terminated and session_end events gain descriptions for termination reasons, open call tracking, and final message ID references.
Command invocation and capability change event documentation schema/draft.json, schema/v0.1.0.json	command_invoke gains descriptions for structured command arguments and expansion text. capability_change gains descriptions for added/removed/changed/snapshot arrays. session_metadata_update variants gain descriptions for field names, values, previous values, and reasons across generic, tags, VCS worktree, and custom field updates. Capability item types (added/removed/changed) gain descriptions for name and field changes.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Poem

🐰 A schema so grand, now speaks clear,
Each field gets a description to revere,
With validation to keep it bright,
The trails of agents documented right! ✨

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch somus/schema-field-descriptions

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[stage-review]

Ready to review this PR? Stage has broken it down into 3 individual chapters for you:

	Title
1	Add field descriptions to draft schema
2	Sync field descriptions to v0.1.0 schema
3	Implement schema description coverage check

_{Chapters generated by Stage for commit 8f3edd0 on Jun 13, 2026 8:13am UTC.}