Lightweight caching and incremental processing

docs/cache-incremental.md

@@ -0,0 +1,73 @@
+# Lightweight Cache and Incremental Processing
+
+`markitect-tool` includes a small file-backed cache manifest for the core CLI.
+It records Markdown file fingerprints and parse summaries so workflows can
+detect which inputs changed before rerunning expensive operations.
+
+This is intentionally not the future SQLite/AST/query backend. That richer
+backend is tracked in `MKTT-WP-0006` and `MKTT-WP-0007`.
+
+## Commands
+
+Fingerprint one file:
+
+```bash
+mkt cache fingerprint docs/example.md
+```
+
+Build or refresh a manifest:
+
+```bash
+mkt cache build docs/ --root .
+```
+
+The default manifest path is:
+
+```text
+.markitect/cache/manifest.json
+```
+
+Check status against the manifest:
+
+```bash
+mkt cache status docs/ --root .
+```
+
+Exit behavior:
+
+- `0`: clean
+- `1`: new, changed, or deleted Markdown files detected
+
+## Manifest Contents
+
+Each entry records:
+
+- relative path
+- SHA-256 content hash
+- size
+- modification time
+- parser identity
+- heading, section, and block counts
+
+The content hash is the authoritative change signal. Modification time and size
+are recorded for diagnostics and future fast-path checks.
+
+## Design Boundary
+
+This layer provides:
+
+- repeatable fingerprints
+- changed/new/deleted detection
+- simple parse summaries
+- a transparent JSON file that can be inspected or removed
+
+It does not provide:
+
+- AST persistence
+- JSONPath querying over cached documents
+- SQLite/FTS indexes
+- vector search
+- policy-aware retrieval
+- distributed cache synchronization
+
+Those belong to later backend workplans.