epic(agent-friendliness): Pass 2+ follow-ups

[jaylfc]

Pass 2+ Follow-ups — agent-friendliness audit

Tracks items deferred from Pass 1 (PR #450). Each unchecked item lands in a future Pass; each Pass cycle starts by ticking items off here.

Pass 2 — first expansion

• Audit + remediate next high-value app (pick at brainstorm time: ChatApp / FilesApp / MemoryApp)
• Per-app agent guides ingestion — community apps bundle `guides/*.md`; ingester walks installed apps with `source_id='app:'`. Forward-prep in Pass 1 commit `f4ddad2`. Tracked separately: Pass 2: per-app agent guides ingestion (App Builder integration) #451
• Concurrency hardening — idempotency in-flight reservation + AgentTokensStore BEGIN IMMEDIATE for multi-worker safety. Tracked separately: Pass 2: concurrency hardening on per-agent tokens + idempotency cache #452
• UI primitive: `ui.spawn_window` — agent spawns a desktop window with arbitrary content
• UI primitive: `ui.drop_file` — agent drops a file into Files.app
• UI primitive: `ui.render_chart` — agent renders a chart in the desktop
• UI primitive: `ui.pin_widget` — agent pins a persistent widget
• Multi-user NotificationStore migration — add `user_id`, `source_type`, `source_id`, `priority`, `action_url` columns + `list_for_user`/`create` API. Unblocks per-user routing for `ui.notify` + restores the `action_url` field on the request schema.
• Rich notifications (buttons, embedded media)
• Cross-device PWA push — agent triggers a PWA notification on user's phone
• Token injection for Docker-backed agents (recreation or tmpfs-mounted secret)
• Token injection for Apple-Containerization agents (mechanism TBD)
• API reference auto-gen for `docs/agents/reference/`
• More A-tier conformance smoke tasks (expand beyond create / notify / token)
• `taosctl auth login` real auth flow (currently `--token` only; add username/password to issue a session)
• `response_model=` on AgentsApp success responses (deferred because agent dicts are loose-typed in Pass 1)

Pass 3 — long tail

• Sweep remaining ~40 apps through the agent-friendliness checklist
• Versioning policy (`/v1/`)
• Rate limiting
• Deprecation policy
• OpenAPI codegen for `taosctl` (if Pass 1+2 prove the pattern)
• Token expiry + rotation policy (time-based, currently operator-initiated only)
• Shell completions for `taosctl` (bash / zsh / fish)

Out-of-scope-permanently (for record)

• MCP as the primary contract (deliberately rejected — REST+CLI+docs is the chosen contract). MCP may land as an optional adapter generated from OpenAPI for clients like Claude Desktop, but it is never the primary surface.

Cross-references

• Pass 1 PR: feat(agents): per-agent API tokens + bearer auth + REST endpoints (audit Pass 1, Phase 1) #450
• Per-app agent guides: Pass 2: per-app agent guides ingestion (App Builder integration) #451
• Concurrency hardening: Pass 2: concurrency hardening on per-agent tokens + idempotency cache #452