[yultyyev]

What

Brings AGENTS.md, and the parts of CONTRIBUTING.md that repeat it, in line with the code on main.

AGENTS.md

• MCP server: replace "MCP server is intentionally out of scope" with what ships, src/mcp/server.ts started by clip mcp.
• Intro: describe the editor as skill + CLI + MCP server + local browser UI.
• Project tree:
  • drop the nonexistent src/preview/ and examples/;
  • add src/mcp, src/ui, src/session, src/storage, src/workspace.ts, src/cli-timeline.ts and src/index.ts;
  • describe timeline/ as the composition document.
• Stack:
  • drop sharp, which isn't a dependency;
  • add the MCP SDK, Hono, React 19 + Vite, and tsup;
  • correct the FFmpeg resolution order: $MAKEMYCLIP_FFMPEG_PATH overrides the bundled binary, and system ffmpeg is the last fallback.
• Non-negotiables:
  • feat: walking skeleton — clip CLI + Claude Code skill (trim tool) #2: the composition is the source of truth for assembled edits, and the single-file tools still render straight from their args.
  • feat(tools): add ingest — probe media and return MediaRef #3: clip ui and MCP paths are confined via resolveInWorkspace, while CLI paths resolve against the current directory.
  • feat(tools): add_text — drawtext overlay with safe escaping #4: @makemyclip/generation doesn't exist yet.
• Naming: note the React app's PascalCase.tsx / useX.ts files, and that config files need a default export.
• Tools:
  • handlers return typed results; ingest, inspect, split, undo and delete-op don't return { path };
  • clip timeline is wired in src/cli-timeline.ts, and the UI exposes tools through src/ui/tool-registry.ts;
  • drop the false claim that the CLI parses argv through the Zod schema.
• FFmpeg:
  • probe.ts is the one direct execa caller;
  • arg builders are mostly one per tool, not one per primitive;
  • compile.ts builds its own filter graphs.
• Testing:
  • type-check covers both tsconfigs, and CI also runs pnpm build;
  • drop the tests/integration/ line, since that directory doesn't exist.
• Commits: add the style type, and replace the unused preview scope with ui. ui is the most-used scope in history (18 commits); preview has none.

CONTRIBUTING.md

• Make the same changes for the ui scope (including the example), handler result shapes, the timeline source of truth and schema location, generation "will live", the CI build step, and the dropped tests/integration/ line.
• Retitle "MCP tools" to "Tools": the MCP tools live in src/mcp/server.ts, not src/tools/.

Backlog: add docs/backlog/cli-input-validation.md. src/cli.ts never runs a tool's Zod *Input.parse, so CLI arguments reach the arg builders unvalidated.

CLAUDE.md is just @AGENTS.md; no change needed.

Why

AGENTS.md is what agents read first, and it described a project shape from before the MCP server, UI and timeline engine shipped.

Not changed (needs a decision)

• Non-negotiable feat(tools): concat — stitch clips back-to-back via concat demuxer #5 vs ffmpeg-static. The rule bans GPL npm packages, but ffmpeg-static's own package.json declares GPL-3.0-or-later. The rule's text only covers the FFmpeg binary.
• "Capitalize first letter of description". CONTRIBUTING.md asks for this, but its own examples and every commit on main use lowercase.
• Rules the code doesn't fully follow. Explicit return types on React exports, is*/has* boolean names, and handler idempotency (output paths use a random id). These are left as rules; the code doesn't fully comply.

Checks

• Every changed statement was checked against origin/main (d4ad0fe): file paths, *Result interfaces in src/tools/, execa, resolveInput and resolveInWorkspace call sites, package.json scripts, ci.yml, .parse( sites, and the commit-scope counts in git log.
• A separate reviewer agent fact-checked the edits against origin/main. I verified and fixed its findings: workspace confinement, the inspect result shape, FFmpeg resolution order, the builder count, the missing style type and the "MCP tools" heading. The items it raised that need a decision are listed above, unchanged.
• Docs-only diff, so no Codex review, per the repo owner's workflow. CI (lint, type-check, test, build) runs on the PR.

[github-actions]

🎉 This PR is included in version 0.3.1 🎉

The release is available on:

• v0.3.1
• GitHub release

Your semantic-release bot 📦🚀