Refresh planning layer for backend fabric

docs/backend-fabric.md

@@ -75,6 +75,37 @@ The resulting `snapshot_id` is a stable hash over those identity fields. This
 lets future AST, JSONPath, FTS, SQL, vector, policy, and context-package
 backends invalidate derived data without guessing what changed.
 
+## Refresh Planning
+
+Before WP-0007 writes a local SQLite index, the backend fabric provides a
+read-only refresh planner. The planner compares current Markdown files with a
+portable snapshot-state inventory and reports:
+
+- unchanged files
+- files that need hashing
+- files that need parsing
+- files that need indexing
+- files that only need metadata updates
+- deleted sources
+- dependency-invalidated dependents
+
+The planner uses a cheap-first strategy:
+
+1. Compare path, size, mtime, parser version, parse options hash, and contract
+   hash.
+2. If cheap metadata is unchanged, skip hashing, parsing, and indexing.
+3. If metadata changed, either mark the file for hash/parse/index or, with
+   `--verify-hashes`, hash only those changed candidates to avoid parsing when
+   content is unchanged.
+4. Use dependency edges to invalidate direct and transitive dependents.
+
+This gives WP-0007 a performance contract before the storage engine exists.
+
+```bash
+mkt backend refresh-plan docs --state examples/backend-state/snapshot-state.yaml
+mkt backend refresh-plan docs --state .markitect/cache/snapshots.yaml --verify-hashes
+```
+
 ## Provenance Envelope
 
 The shared backend provenance envelope records:
@@ -113,6 +144,7 @@ Read-only inspection commands:
 mkt backend list --path examples/backends
 mkt backend inspect local-sqlite-cache --path examples/backends --require snapshots --require provenance
 mkt backend snapshot-id docs/content-references.md
+mkt backend refresh-plan docs --state examples/backend-state/snapshot-state.yaml
 ```
 
 The existing `mkt cache status` remains the lightweight file-manifest change