feat: StudyOS data and action capability contract

[SebastianBoehler]

Issue Spec: StudyOS Data And Action Capability Contract

Summary

Define a shared capability layer for StudyOS data reads and user-approved actions, so the proactive feed, assistant runtime, generative UI, and voice input branches can all use the same contracts.

Goal

Prevent every branch from inventing separate access patterns for calendar, university data, Mensa, navigation, deadlines, and app actions.

Scope

• Define typed read capabilities such as getSchedule, getDeadlines, getMensaOptions, and getRouteHint.
• Define typed action capabilities such as openNavigation, openCourseDetail, createReminder, or openMensa.
• Add privacy labels, for example local_only, user_approved, or external_call.
• Provide mock implementations for demos and tests.
• Make unavailable capabilities fail explicitly.
• Include capability freshness metadata such as fetchedAt, expiresAt, and source reliability where useful.

Out Of Scope

• Scraping the existing Flutter app internals.
• Implementing every university integration at once.
• Hosted credential storage or credential routing.
• Silent mock production data.

Acceptance Criteria

• Capabilities have typed request and response shapes.
• Each capability documents data source, privacy level, and failure modes.
• Cacheability and recommended refresh behavior are documented per capability.
• Mock implementations are available for at least schedule, next deadline, and route hint.
• Consumers can distinguish real data, mock data, unavailable data, and permission-denied data.
• The proactive feed and assistant runtime can depend on these contracts without knowing the underlying source.

Gates To Pass

• Contract gate: each capability has explicit input, output, errors, and privacy notes.
• Freshness gate: consumers can tell whether data is fresh, stale, unavailable, or permission-denied.
• Privacy gate: credentials and sensitive data stay local unless the user explicitly approves otherwise.
• Reuse gate: at least two planned branches can consume the same capability interface.
• Reliability gate: unavailable data produces visible fallback behavior, not silent fake values.
• Test gate: mock and unavailable capability states are covered by tests or documented checks.
• Demo gate: a reviewer can run a local demo without live university credentials.

Suggested Branch

feat/capability-contract