refactor(tools): tighten platform tool schemas; storage-symmetric shape

[mgoldsborough]

Summary

The LLM-facing JSON Schema is a contract. A loose manifest: { type: "object" } invites the model to invent structure under-spec — saw this in production conv_30076c3681ad4c91 where Sonnet serialized the manifest as a JSON-string because the schema had no inner shape, then the validator rejected it, and the user saw "Couldn't create" with no signal what went wrong.

This PR applies four invariants across every platform tool that authors a persistent thing, plus a directory-scoped CLAUDE.md (symlinked as AGENTS.md) so future contributors author against the convention rather than retrofit.

Four invariants

1. MCP-native — built via defineInProcessApp, surfaces through tools/list / tools/call byte-identical to a subprocess MCP server. Same wire format external clients (Claude Code, Cursor, Claude Desktop) consume.
2. Strict input schemas — every object declares properties; every array declares items; identifiers use pattern; constrained strings use enum; bounded numbers use minimum/maximum. Locked by test/unit/tools/platform/schema-shape.test.ts.
3. Storage-symmetric shape — create/update tools use { scope?, manifest, body } where manifest mirrors the on-disk metadata field-for-field and body is the content payload. No name at root, no flat-config-at-root.
4. Minimum sufficient surface — operator/runtime-set fields (source, bundleName, allowedTools, requiresBundles, overrides, derivedFrom) live on the type and the on-disk file, not in the LLM-facing schema.

Per-tool changes

Tool	Change
skills__create / update	Full SkillManifest mirror; name moved into manifest; nested metadata for keywords/triggers/category/tags; dropped allowedTools, requiresBundles, loadingStrategy, appliesToTools, overrides, derivedFrom from LLM input
instructions__write_instructions	Renamed text → body for cross-tool consistency
automations__create / update	Restructured to {manifest, body}; prompt → body; manifest holds schedule + run-time policy; dropped allowedTools, source, bundleName from input
files__create	Restructured to {manifest, body}; base64_data → body; mime_type → mimeType

Deleted

• src/skills/manifest-input.ts — loose-shape coercion accepting kebab/snake/camel variants. The schema is the contract; one casing wins; the validator enforces it.

Added

• src/tools/platform/CLAUDE.md (with AGENTS.md symlink) — directive, ~200 lines, the four invariants and an "adding a new tool" checklist. Authoring rules for any future platform tool.
• test/unit/tools/platform/schema-shape.test.ts — walks every source's tools/list, recursively asserts every object has properties and every array has items. Locks invariants (1) and (2) against future regression. New sources register in the test's SOURCES array; new tools on existing sources are auto-detected.

No backward compat

Clean break. Handlers cast directly to typed interface CreateInput/UpdateInput since the validator already enforced the schema upstream — no defensive re-validation, no kebab/snake/camel coercion, no flat-field plucking. The LLM rebuilds its tool understanding every conversation; there is no migration window to bridge.

Test plan

• bun run verify green: 2129 unit, 213 web, 416 integration, 17 smoke
• schema-shape.test.ts passes — locks (1) and (2) for skills, instructions, files, conversations
• Existing skill / automation / file tests updated to new shape (no compat layer)
• Manual: create a workspace skill via the chat agent — confirm the agent produces the new shape correctly with no validator rejection
• Manual: create an automation via the chat agent — same
• Manual: upload a file via files__create from the agent — same

Files

• src/tools/platform/skills.ts — schema rewrite, handler simplification, types import
• src/tools/platform/instructions.ts — text → body
• src/tools/platform/files.ts — schema rewrite, handler refactor
• src/bundles/automations/src/schemas.ts — full schema rewrite
• src/bundles/automations/src/server.ts — handler rewrite, removed containsRecursiveTool (dead code; allowedTools no longer reachable from input)
• src/skills/manifest-input.ts — DELETED
• src/skills/index.ts — drop coercer export
• src/tools/platform/CLAUDE.md — new convention doc
• src/tools/platform/AGENTS.md — symlink to CLAUDE.md
• test/unit/tools/platform/schema-shape.test.ts — new lint
• test/**/*.test.ts — multiple test fixtures updated to new shape
• web/src/pages/settings/components/WorkspaceInstructions.tsx — body field rename

[mgoldsborough]

QA review adjudication — fixed in 263fb05

All 9 issues addressed. The three criticals shared one root cause: the LLM-facing tool was the only caller of the automation domain, so when we tightened its schema the CLI and lifecycle paths silently broke.

Architectural fix — domain API

Extracted src/bundles/automations/src/domain.ts exporting createAutomation / updateAutomation / deleteAutomation. Accepts the full Automation shape including operator fields (source, bundleName, allowedTools). The tool handlers become thin schema-translators that delegate to the domain and stamp source: "agent". Internal callers (CLI, lifecycle) bypass the LLM-facing surface and call the domain directly via a runtime-exposed getter.

CLAUDE.md § 1.4 codifies the rule: internal callers use the domain API, not the tool handler.

Per-issue resolution

#	Status	Fix
1	✅	CLI pause/resume calls updateAutomation(name, { enabled }, ctx) directly. New domain.test.ts regression suite asserts enabled actually flips end-to-end.
2	✅	lifecycle.ts::syncBundleAutomations calls createAutomation from domain with full shape.
3	✅	Same call sets source: "bundle" + bundleName. removeBundleAutomations reads the store directly via ctx.definitions() and finds matching entries.
4	✅	automations registered in schema-shape.test.ts SOURCES.
5	✅	containsRecursiveTool restored, applied at the executor (sees the merged Automation regardless of authoring path). Three new executor tests cover reject-create / reject-update / permit-non-recursive.
6	✅	validateAutomationFields(args: ValidatableAutomationFields) — typed signature, no synthetic flat-record cast.
7	✅	SKILL_UPDATE_MANIFEST_PROPERTIES and AUTOMATION_UPDATE_MANIFEST_PROPERTIES derived via Omit<..., "name">. Schema rejects renames at validation.
8	Defer	TODO comment unchanged — out of scope for this PR. Will spin a follow-up for the chat-multipart MIME allowlist.
9	✅	UPDATABLE_FIELDS in domain.ts now matches Automation type declaration order; comment explains why.

Verify: 2151 unit (+9 new), 213 web, 416 integration, 17 smoke — all green.