browser/openspec/changes/sync-implemented-docs-and-comments/design.md

Overview

This is a documentation synchronization change. The codebase already implements the capabilities being clarified; the work is to remove stale "gap" and "deferred" language where it contradicts the current route catalog and tests, while leaving real future-work boundaries visible.

Scope

• Update stale route/protocol/frontend/plugin documentation and API comments.
• Do not alter request/response contracts, validators, services, frontend components, plugin SDK behavior, or run execution logic.
• Do not mark future features as implemented unless an implemented route/client/test already exists.

Target Corrections

• Frontend API contracts should show platform and server metrics endpoints as implemented.
• AI provider protocol docs should show platform-mediated invocation as implemented while keeping live connectivity and remote model discovery deferred.
• Run artifact protocol docs should show browser download as implemented while keeping platform-to-run download, browser upload, external object storage, presigned URLs, and production throttling as future work.
• Platform API route docs should remove already-implemented config diff/file dispatch from deferred route groups.
• Handler Swagger comments for artifact/log metadata should not claim implemented chunk ingest or durable log ingest remains deferred.
• Plugin README should no longer describe marketplace, hosted plugin pages, or real lifecycle execution as future OpenSpec work when those flows now exist in bounded platform-mediated form.

Validation

• Run a focused stale-marker scan for the corrected files.
• Run scripts/check-structure.sh.
• Run openspec validate sync-implemented-docs-and-comments --strict.

No browser walkthrough is required because this change does not edit frontend pages or visual behavior.