[aicayzer]

Summary

Folders created before the search to query rename in #2371 retain search, which the current CLI refuses to read. Folder changes previously merged settings without removing it, so even a complete corrected document could not restore sync. Every accepted folder change now removes stored properties the current folder type does not declare.

Changes

• Preserve partial updates: replace each named setting whole and retain omitted declared settings. Prune undeclared properties after version resolution, inside the same transaction, before validation and persistence.
• Preserve version conflicts, stale disjoint merges, validation, and the restriction on direct system-item writes. No search alias or translation is introduced.
• State the rule in the folder-operation contract and update CLI help, the command reference, OpenAPI, and generated client documentation.
• Add server regressions and a CLI fixture that seeds older stored settings, witnesses the open refusal, repairs through --file and --body, reads back the exact settings, and opens and syncs the folder.

Testing

• Observed both server regression cases and both CLI recovery cases fail before the fix because search and another undeclared property survived.
• Passed the folder route, item-version, property-merge, conflict, and OpenAPI style tests (92 tests across five files).
• Passed both CLI recovery cases against a real isolated server and the built CLI.
• Passed contract citations (16 tests), CLI command-reference checks (12 tests), server and conformance typechecks, focused ESLint and Prettier checks, and Rust formatting.
• Built the workspace and CLI. Local tests were limited to the affected behavior and its version/merge path.

Notes for reviewers

Review performed: traced the folder handler through the shared writer, both current and stale storage-update paths, conflict resolution, validation, persistence, and CLI callers. The internal pruning control is enabled only by the folder-change route; ordinary item writes retain their existing behavior. This data-write change needs review of version handling and the upgrade fixture.

Pruning every accepted change avoids guessing whether a JSON document is complete and preserves existing partial-update semantics. It does not interpret removed settings. Callers repairing an older folder must supply the intended query.

Docs follow-up, checked with marfa docs search 'folders change': Sync a folder, under “Change a folder's settings,” should explain that named settings replace whole, omitted declared settings stay, and every accepted change removes undeclared stored properties. Include repair via folders change --version N --file settings.json or --body with the intended query. The docs repository was intentionally not edited. Its generated API reference also needs the updated OpenAPI description on its next import.

Leave this pull request open for review; do not merge.

Checklist

• The title is a scoped Conventional Commit.
• New behavior has a test that was seen failing first, or no test was needed and the reason is above.
• Docs, comments and the contract still say what is true after this change; the separate docs-site follow-up is identified above.

[aicayzer]

Reviewed with Codex against origin/main: no regressions; focused folder, item-write, version and property-merge tests pass, and the new CLI conformance test passed in CI. Found on a real instance upgraded from v0.0.28: without this, a folder made before the search-to-query rename cannot be brought forward. Merging on green checks.