jedarden
c5238b1bcd
docs(troubleshooting): add common issues guide and diagnostic playbook (P11.5)
...
Implements P11.5 acceptance criteria:
- Created docs/troubleshooting.md with 10 common issues
- Created docs/troubleshooting/diagnostics.md with systematic diagnostic playbook
- Documented 3 required plan §11 issues (primary key required, degraded search results, stuck tasks)
- Added 7 additional issues from Phase 9 chaos testing and operations
- Cross-linked from README, migration runbook, and dump import guide
Documented issues:
1. "primary key required" - Miroir vs Meilisearch difference
2. Search returns fewer results - degraded node handling
3. Task polling stuck - per-node task status recovery
4. Node drain blocked - RF constraints
5. Migration stuck after coordinator crash - recovery procedures
6. High memory usage on Redis - cleanup procedures
7. Index creation fails - topology inconsistency
8. Alias flip conflicts - single vs multi alias types
9. Search timeout during migration - throttling options
10. CDC cursor out of sync - recovery and re-index
Diagnostic playbook covers:
- Cluster health checks (pods, nodes, resources)
- Topology verification and node agreement
- Metrics analysis (degraded shards, task queue, latency)
- Log analysis for error patterns
- Task status inspection
- Anti-entropy status
- External dependency checks
- Self-diagnostics and canary tests
Closes: miroir-uyx.5
2026-05-24 14:02:13 -04:00
jedarden
5fc044acf9
docs: add feature matrix and badges to README.md (P11.1, miroir-uyx.1)
...
- Add badges: CI (Argo Workflows), License (MIT), SemVer 2.0.0
- Add feature matrix with all 21 §13 advanced capabilities and defaults
- Add Documentation section with links to design plan, CHANGELOG, Helm chart, deployment guides, and migration runbook
- Remove outdated "Status: Design phase" section
Closes: miroir-uyx.1
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
2026-05-24 08:59:48 -04:00
jedarden
02ad8fce9b
P11.7: Add quick-start example artifacts (Docker Compose + config)
...
Adds the on-disk examples referenced by plan §11 "Quick start (local, Docker Compose)":
- examples/docker-compose-dev.yml: 3 Meilisearch nodes + 1 Miroir orchestrator
- examples/dev-config.yaml: Matching Miroir config (16 shards, RF=1)
- examples/README.md: Comprehensive docs for running, troubleshooting, teardown
- k8s/argo-workflows/miroir-ci-docker-compose-smoke.yaml: CI smoke tests
The README.md quick start section already references these examples.
Acceptance:
✅ docker-compose-dev.yml boots via docker compose up
✅ dev-config.yaml mounted into Miroir container
✅ examples/README.md documents usage and teardown
✅ CI smoke job exercises compose stack (health + index + search tests)
✅ README.md quick start points to examples/docker-compose-dev.yml
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Bead-Id: bf-3lad
2026-05-20 06:50:43 -04:00
jedarden
f20c1bae4d
bf-1p4v: Verify compile error already fixed
...
The borrow-of-moved-value error for `state` was already fixed in the codebase.
Line 568 uses `.with_state(state.clone())` and `UnifiedState` derives Clone.
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
2026-05-20 06:49:04 -04:00
jedarden
e348157283
P11.9 v1.0 versioning-commitments policy doc (§12)
...
- Add CHANGELOG.md preamble referencing versioning policy
- Add README.md Stability section linking to versioning policy
The versioning policy document already existed at docs/versioning-policy.md
with all four v1.0 commitments from plan §12.
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
2026-05-20 06:41:27 -04:00
jedarden
409f952f59
Add repo hygiene: LICENSE, CHANGELOG, .gitignore
...
- LICENSE: MIT (per plan §12)
- CHANGELOG.md: Keep a Changelog 1.1.0 skeleton with [Unreleased]
and [0.1.0] sections matching the awk extractor from plan §7
- .gitignore: Rust target/, editor junk; Cargo.lock kept in VCS
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
2026-04-18 20:47:36 -04:00
