docs: align architecture, protocol, and module design docs

[jinyu918]

Summary

This PR aligns the repository design docs with the approved documentation updates and refreshes the architecture overview to match the current system framing.

It includes documentation-only changes in:

• docs/protocol-design.md
• docs/module-design.md
• docs/architecture-overview.md

No runtime code or protocol implementation was changed in this PR.

What changed

1. Protocol design alignment

Updated docs/protocol-design.md to reflect the approved protocol-level constraints and semantics, including:

• agent.settings.model.validate as a stable method
• request/response examples and field-level documentation
• settings snapshot vs settings/model patch boundaries
• validate -> update consistency via:
  • validated_config_hash
  • expected_validated_config_hash
• detached bubble semantics
• context canonicalization rules
• screen_capture Task / Run source consistency
• clarified meaning of run_status = completed
• distinction between plugin_runtime_status and plugin_health_status
• boundary between:
  • agent.delivery.open
  • agent.task.artifact.open
• unified SecuritySummary baseline
• subscription transport and notification refresh rules

2. Module design alignment

Updated docs/module-design.md to reflect the approved module-level design boundaries, including:

• Harness as the single task-state and runtime-orchestration authority
• refined expectations for /packages/protocol/schemas
• phased validation expectations for the local access layer:
  • P0
  • P1
  • P2
• progressive handling of request_meta.trace_id
• separation of request vs subscription adapters on the frontend side
• notification as a refresh trigger, not a long-term source of truth
• model integration through a Model Provider Adapter
• model integration maturity boundaries
• settings save flow with validation before update
• detached bubble handling at the module layer
• context canonicalization in TaskContextSnapshot
• result-opening boundaries for delivery vs artifact entry points
• unified SecuritySummary service model

3. Architecture overview refresh

Updated docs/architecture-overview.md to better match the current system framing and improve readability at the architecture level.

Main updates include:

• reframing the system around independently evolving modules rather than only layered descriptions
• clarifying module responsibilities and dependency boundaries for:
  • desktop interaction
  • local access
  • task runtime
  • governance
  • delivery
  • capability gateway
  • local data
  • long-term collaboration
• clarifying the relationship between formal external objects and execution-compatible runtime objects:
  • Task
  • Run
  • Step
  • Event
  • ToolCall
  • governance / delivery / memory-related objects
• separating module dependency explanation from business-flow sequencing
• refining architecture terminology and appendix mappings

Impact

This PR is documentation-only.

It makes the architecture, protocol, and module design docs more consistent around:

• task-centric system boundaries
• module responsibilities and dependencies
• protocol object semantics
• model settings validation and save flow
• detached bubble vs formal task/delivery boundaries
• notification/query refresh responsibilities
• security summary and plugin runtime semantics

Notes

These changes intentionally focus on approved documentation scope and architecture clarification.

Where the docs introduce stricter protocol expectations, follow-up implementation work may still be required in:

• TypeScript protocol types
• JSON Schema assets
• Go backend behavior
• frontend service / adapter usage

Validation

• only documentation files were changed
• no runtime logic was modified
• updates were merged and organized according to the approved documentation change direction

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!