docs: metadata schema evolution protocol

[FSM1]

Summary

• Adds docs/METADATA_SCHEMAS.md — complete reference for all 10 encrypted metadata objects (FolderMetadata, FileMetadata, DeviceRegistry, VersionEntry, etc.) with field tables, encryption hierarchy, cross-implementation parity matrix, and IPNS key derivation summary
• Adds docs/METADATA_EVOLUTION_PROTOCOL.md — formal rules for evolving metadata schemas: additive vs breaking change classification, dual-platform (TypeScript + Rust) checklist, version bump conventions, testing requirements, and recovery tool compatibility matrix
• Adds learnings entry cross-referencing both docs

No code changes — documentation only.

Test plan

• Verify both docs render correctly on GitHub
• Verify MEMORY.md references both docs for future sessions
• Confirm no source code was modified

🤖 Generated with Claude Code

Summary by CodeRabbit

• Documentation
  • Added comprehensive metadata schema reference documentation covering all metadata types, encryption schemes, and storage locations.
  • Introduced formal metadata evolution protocol specifying versioning guidelines, change classifications, and cross-platform validation requirements.

[coderabbitai]

Walkthrough

This PR introduces formal documentation for CipherBox metadata schema evolution, creating comprehensive reference guides for 10 metadata types and establishing a protocol for managing schema changes across TypeScript and Rust implementations.

Changes

Cohort / File(s)	Summary
Planning & Learning .learnings/2026-02-21-metadata-schema-evolution-protocol.md, .planning/STATE.md, .planning/quick/019-metadata-schema-evolution-protocol/019-PLAN.md, .planning/quick/019-metadata-schema-evolution-protocol/019-SUMMARY.md	Captures lessons learned from metadata schema work, updates project state tracking, and documents the metadata documentation task plan and completion summary.
Reference Documentation docs/METADATA_SCHEMAS.md, docs/METADATA_EVOLUTION_PROTOCOL.md	Introduces two comprehensive reference documents: METADATA\_SCHEMAS.md detailing all 10 metadata object types with field definitions, encryption schemes, and version histories; METADATA\_EVOLUTION\_PROTOCOL.md defining versioning rules, breaking vs. additive change classifications, cross-platform validation requirements, and recovery tool compatibility guidelines.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related PRs

• docs: milestone 2 & 3 planning #101 — Addresses metadata schema evolution and introduces TypeScript types for FolderMetadata v2, directly aligning with the schema definitions and versioning rules documented in this PR's evolution protocol.

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and specifically summarizes the main change: adding formal metadata schema evolution protocol documentation.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch docs/metadata-schema-evolution-protocol

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@docs/METADATA_SCHEMAS.md`:
- Around line 339-340: Update the documentation descriptions for
DeviceEntry.publicKey and deviceId to reference secp256k1 instead of Ed25519:
change the deviceId description to "SHA-256 hash of device's secp256k1 public
key (64 hex chars)" and change the publicKey description to "Device's secp256k1
public key, uncompressed (130 hex chars)"; ensure the two lines describing
`deviceId` and `publicKey` in METADATA_SCHEMAS.md mention the secp256k1 key type
to match the validator that enforces 130 hex chars for publicKey.