feat: add you-md export to write preferences into each tool's native instruction file

[brainsparker]

What this does

Adds a you-md export command that writes your you.md preferences into each AI tool's native instruction file. This is the outbound counterpart to the existing convert command: tools that do not speak MCP (or that you have not wired the skill into) still get your preferences, because they already read these files at session start.

you-md export --all               # export to every supported tool
you-md export claude gemini      # export to specific tools
you-md export --all --dry-run    # preview paths and actions, write nothing
you-md export claude -o out.md   # override output path (single target)

Targets: claude (/.claude/CLAUDE.md), codex (/.codex/AGENTS.md), gemini (~/.gemini/GEMINI.md), windsurf (global_rules.md), cursor (.cursor/rules/you-md.mdc), agents (./AGENTS.md).

Exports are idempotent. Managed content lives between <!-- you-md:begin --> and <!-- you-md:end --> markers, so hand-written content in the same file is preserved and re-exports update the block in place. Existing files are backed up to <file>.backup before every write. The cursor target writes a dedicated .mdc rule file (with alwaysApply: true frontmatter) that you-md owns entirely.

Why now (market rationale)

1. AGENTS.md and per-tool instruction files are now how developers configure AI tools. As of mid 2026 the AGENTS.md standard is read by 30+ tools across 60k+ repos and is stewarded by the Linux Foundation's Agentic AI Foundation (2026 guide, compatibility matrix). Claude Code, Gemini CLI, and Codex each also read a user-level file (~/.claude/CLAUDE.md, ~/.gemini/GEMINI.md, ~/.codex/AGENTS.md). Those files are exactly where you.md content belongs.
2. Every competing sync tool is repo-scoped, none is user-scoped. agentsync (Apr 2026), config-sync (Apr 2026), and agentdef (May 2026) all sync repo rules between formats. None of them answers "who am I and how do I like to work" portably across tools, which is you.md's stated thesis. The recurring complaint they cite ("update conventions, update seven files", see also BaseThread, May 2026) applies with equal force to user-level preferences, and nothing serves it today.
3. The repo already had the inbound half. you-md convert .cursorrules pulls other formats in, and the MCP youmd_tool_config tool generates per-tool snippets but never writes them anywhere. Export closes the loop and makes you.md useful even for tools where the MCP skill is not installed.

Runner-up candidates considered today and passed on: JUnit XML output plus fail-on-threshold CI gating for PromptLens (timely given promptfoo's acquisition by OpenAI in March 2026, but the repo has 33 stale automated PRs touching adjacent code, high overlap risk), and profile-scoped tools/list filtering for MCP-Profiles using the ttlMs/cacheScope cache hints added in the 2026-07-28 MCP spec (strong first-mover window, but higher spec-interpretation risk for a one-day build).

Implementation notes

• New src/cli/commands/export.ts: target registry, managed-block merge logic (applyManagedBlock), atomic writes (tmp file + rename) with .backup copies, matching the existing conventions in skill.ts.
• New src/core/formatter.ts: the context formatter previously private to the MCP server, now shared. src/mcp/server.ts delegates to it (net deletion there), so MCP output and exported files stay byte-identical.
• src/cli/args.ts and src/cli/index.ts: register the export command plus --all and --dry-run flags, help text updated.
• test/cli/export.test.ts: vitest suite covering marker wrapping, idempotent re-apply, user-content preservation, backups, cursor own-file mode, path scoping, and output override.
• README: quick reference entry plus a full you-md export section with a target table.

Test status

• New vitest suite included (test/cli/export.test.ts, 13 cases mirrored end to end).
• The build sandbox for this run could not reach the npm registry (egress policy), so vitest/tsc could not be installed there. All 13 test cases plus a full end-to-end exportCommand run against a real .you.md fixture (discovery, dry-run, unknown-target and flag-validation error paths) were executed against the actual source with Node 24 native type stripping and pass. Please run npm test and npm run lint on a machine with registry access before merging.