docs: clarify capabilities and contracts

[Thelastpoet]

Summary

• What changed
• Why it changed

Spec References

• Task ID(s):
• RFC(s):
• ADR(s):
• API/schema files:

Behavior and Compatibility

• Behavior change:
• Backward compatibility impact:

Validation

• python -m pytest -q
• python scripts/check_contract.py
• DB integration tests run (if applicable)

Migrations and Ops Notes

• Migration files:
• Rollout/rollback notes:

Checklist

• Specs updated before implementation
• contracts/docs updated when behavior changed
• Tests added/updated for behavior changes