# NotesRecover

> Copy-first Apple Notes recovery and review toolkit for macOS, with AI-assisted triage, evidence-backed case Q&A, and a read-mostly MCP surface for Codex / Claude Code style local agent workflows.

## Canonical URLs

- Landing: https://xiaojiou176-open.github.io/notes-recover/
- Repository: https://github.com/xiaojiou176-open/notes-recover
- Releases: https://github.com/xiaojiou176-open/notes-recover/releases
- PyPI: https://pypi.org/project/notes-recover/

## Start Here

- README.md: primary public contract and operator-first path
- proof.html: public proof, remote read-back, and manual external boundary
- CONTRIBUTING.md: canonical verification contract
- USE_CASES.md: operator and builder use cases
- ECOSYSTEM.md: ecosystem fit matrix
- INTEGRATIONS.md: builder guide and substrate status

## What This Project Is

- copy-first Apple Notes recovery and review toolkit
- macOS local-boundary workflow
- case-root-centric artifact pipeline
- reviewable outputs first
- public-safe / derived-artifact-first AI layer
- local read-mostly MCP surface for builder and local-agent workflows

## What Shipped Today

- `notes-recovery demo`
- `notes-recovery doctor`
- `notes-recovery ai-review`
- `notes-recovery ask-case`
- `notes-recovery plugins-validate`
- `notes-recovery case-diff`
- `notes-recovery-mcp`
- `plugins/notes-recover-codex-plugin/`
- `plugins/notes-recover-claude-plugin/`
- `.claude-plugin/marketplace.json`
- `skills/notes-recover-case-review/`
- `server.json`
- GitHub Pages landing at `/`

## Fastest Proof Commands

- `notes-recovery demo`
- `notes-recovery ai-review --demo`
- `notes-recovery ask-case --demo --question "What should I inspect first?"`
- `notes-recovery doctor`
- `.venv/bin/python -m notes_recovery.mcp.server --case-dir ./output/Notes_Forensics_<run_ts>`

## AI / Agent / MCP Fit

- Primary fit: MCP, Codex, Claude Code
- Secondary / comparison fit: OpenHands, OpenCode
- OpenClaw: installable compatible bundle path exists; the secondary ClawHub public-skill listing is live, but that does not imply a live OpenClaw bundle listing
- Not a primary front-door claim: hosted portals and generic agent-platform promises

## Host Notes

- Codex and Claude Code are both good current examples of hosts that fit the shipped local stdio MCP surface here.
- Keep the same local stdio command as the source of truth even when each host wraps it differently.
- INTEGRATIONS.md still includes the minimal `.mcp.json` wrapper example, and `DISTRIBUTION.md` tracks the current PyPI lane contract, shipped plugin bundles, marketplace manifest, and MCP Registry boundary without turning them into permanent live claims.
- The tracked Codex bundle includes `.codex-plugin/plugin.json`, a local marketplace example, and the bundled MCP launcher under `plugins/notes-recover-codex-plugin/`.
- When you need the literal project config token, the tracked Codex example still maps to `.codex/config.toml` through the bundle layout.
- Treat remote-connector-first hosts as comparison paths here because this repo does not ship a hosted or remote MCP deployment.
- OpenClaw-style hosts can now consume a shipped compatible bundle, but this repo still does not claim an official listing.
- Fastest host smoke: `demo` -> `ask-case --demo` -> register the exact `notes_recovery.mcp.server` command.

## What Not To Assume

- no shipped hosted API
- no OpenAPI contract
- no generated client
- no formal SDK platform
- no hosted review portal
- no team collaboration layer
- no write-capable MCP by default
- no official marketplace listing today
- AI is not the recovery engine

## Builder Substrate

- `notes-recovery`
- case roots
- manifests
- review artifacts
- `notes-recovery-mcp`
- `plugins/`
- `.claude-plugin/marketplace.json`
- `server.json`
- bounded `case-diff`
- bounded `plugins-validate`

## Source Of Truth

- README.md
- CONTRIBUTING.md
- SECURITY.md
- SUPPORT.md
- CHANGELOG.md
- USE_CASES.md
- ECOSYSTEM.md
- INTEGRATIONS.md
