feat(agent): add structured outputs and media archive support

docs/agents/authoring.md

@@ -0,0 +1,128 @@
+# Agent Authoring Guide
+
+This guide describes how to add or evolve agents after the runtime redesign.
+
+## Acceptance Checklist (Task Gate)
+
+Before shipping agent doc or definition changes, confirm all points are documented in the PR notes:
+
+- Runtime definition location and ownership.
+- How markdown prompt segments affect prompts through compile-time extraction.
+- What a new agent must define in TypeScript.
+- Expected structured output shape (`artifactType`, `sections`, `metadata`, `qualityChecks`, `previewText`, `body`).
+- Tests added for definitions, prompt compilation, prompting, and contracts.
+
+## Dual Model: Source of Truth Rules
+
+The agent runtime uses two complementary sources of truth:
+
+1. Structural/runtime contract in TypeScript.
+   - `lib/agent-definitions.ts`: registry (`AGENT_DEFINITIONS`), metadata, rules, blueprints, docs path.
+   - `lib/agent-run-contract.ts`: normalization and safety for plans, clarifications, and structured outputs.
+   - `lib/agent-templates.ts`: UI projection derived from definitions.
+2. Curated prompt influence in markdown.
+   - `components/agents/<agent-id>.md` contains authored narrative plus marked prompt segments.
+   - `scripts/compile-agent-docs.ts` extracts only marked blocks.
+   - `lib/generated/agent-doc-segments.ts` is generated and consumed at runtime.
+
+No free-form markdown parsing happens in `convex/agents.ts`.
+
+## Add a New Agent
+
+1. Add a definition in `lib/agent-definitions.ts`.
+   - Add a new `AgentDefinitionId` union member.
+   - Add a new item in `AGENT_DEFINITIONS` with metadata, rules, accepted source types, and `defaultOutputBlueprints`.
+   - Set `docs.markdownPath` to the companion markdown file.
+2. Add companion markdown in `components/agents/<agent-id>.md`.
+3. Compile prompt segments into `lib/generated/agent-doc-segments.ts`.
+4. Add i18n entries for template and output labels in `messages/de.json` and `messages/en.json` when needed.
+5. Add or update tests (see test matrix below).
+
+## Marker Rules (Required)
+
+Every agent markdown file must include exactly one start marker and one end marker for each required key:
+
+- `role`
+- `style-rules`
+- `decision-framework`
+- `channel-notes`
+
+Marker format:
+
+```md
+<!-- AGENT_PROMPT_SEGMENT:role:start -->
+Your segment text.
+<!-- AGENT_PROMPT_SEGMENT:role:end -->
+```
+
+Constraints:
+
+- Marker names must match exactly.
+- Missing, duplicate, or empty segments fail compilation.
+- Segment order in output is deterministic and follows `AGENT_PROMPT_SEGMENT_KEYS`.
+- Unmarked prose is ignored by the runtime prompt payload.
+
+## Compile Flow
+
+Run the compiler after changing any `components/agents/*.md` marker content or any `docs.markdownPath` entry:
+
+```bash
+npx tsx scripts/compile-agent-docs.ts
+```
+
+Then verify generated output changed as expected:
+
+- `lib/generated/agent-doc-segments.ts`
+
+## Structured Output Expectations
+
+Execution payloads are normalized via `normalizeAgentStructuredOutput(...)` in `lib/agent-run-contract.ts`.
+
+The runtime expects:
+
+- `title`
+- `channel`
+- `artifactType`
+- `previewText`
+- `sections[]` (`id`, `label`, `content`)
+- `metadata` (`Record<string, string | string[]>`)
+- `qualityChecks[]`
+
+Compatibility behavior:
+
+- `body` stays as a legacy fallback string for old render paths.
+- Missing/invalid entries are normalized defensively.
+
+## Test Matrix for Agent Changes
+
+For a new agent or blueprint change, add or update tests in these areas:
+
+- Definition registry and projection
+  - `tests/lib/agent-definitions.test.ts`
+  - `tests/lib/agent-templates.test.ts`
+- Markdown marker extraction and generated segment coverage
+  - `tests/lib/agent-doc-segments.test.ts`
+- Prompt assembly behavior
+  - `tests/lib/agent-prompting.test.ts`
+- Runtime contracts (execution plan + structured output normalization)
+  - `tests/lib/agent-run-contract.test.ts`
+  - `tests/lib/agent-structured-output.test.ts`
+- Convex orchestration behavior when contract semantics change
+  - `tests/convex/agent-orchestration-contract.test.ts`
+
+## When `convex/agents.ts` Stays Unchanged
+
+Do not modify `convex/agents.ts` when you only:
+
+- add a new definition entry in `lib/agent-definitions.ts`
+- add/update markdown prompt segments and recompile
+- add or adjust output blueprints using existing contract fields
+- tune analysis/execution rules in definitions
+- update UI copy or i18n labels
+
+Modify `convex/agents.ts` only when orchestration semantics change, for example:
+
+- new runtime stage/state transitions
+- credit/scheduler behavior changes
+- schema shape changes for analyze or execute payloads
+- persistence shape changes beyond current normalized contracts