docs: add project vision

docs/VISION.md

@@ -0,0 +1,223 @@
+# MinerOps
+
+## Operational Intelligence for Mining
+
+## Mission
+
+MinerOps combines real-time operational awareness, durable asset identity,
+repair intelligence, spatial visualization, historical analytics, and
+actionable context in one self-hosted platform. It helps operators understand
+what is happening, why it is happening, and what should happen next.
+
+## Product Vision
+
+MinerOps transforms operational data into useful decisions across the full
+lifecycle of a mining operation. It connects live conditions to the durable
+identity, location, repair history, component context, and prior performance of
+the equipment involved. The goal is practical operational clarity: observations
+should lead to explanations, priorities, and safe next actions.
+
+The current product is an early-stage operational application with foundations
+for authentication, inventory and identity, telemetry, locations, repair
+workflows, control-board replacement, repair-part records, and a minimal tracked
+component registry. These foundations do not yet constitute the complete vision.
+Advanced spatial workflows, comparative time-series analytics, generalized
+component movement and genealogy, donor workflows, and decision support remain
+future direction unless an approved implementation task establishes otherwise.
+
+## Product Pillars
+
+### 1. Operations
+
+Operations turns live fleet state into an understandable work queue. It covers
+health, availability, alerts, safe controls, and prioritized next actions—for
+example, identifying miners that are offline, overheating, unstable, or awaiting
+intervention.
+
+### 2. Assets
+
+Assets gives every miner and meaningful tracked component a durable identity
+independent of mutable network addresses, hardware assignments, and physical
+location. Examples include Asset IDs, lifecycle state, MAC history, component
+identity, and movement history.
+
+### 3. Repairs
+
+Repairs preserves the context and outcome of maintenance work. Examples include
+repair episodes, ordered timelines, diagnostics, parts used, control-board
+replacement, testing, and return-to-service decisions.
+
+### 4. Spatial Intelligence
+
+Spatial Intelligence explains operations through the physical structure of the
+mine. It connects sites, rooms, racks, shelves, miners, work areas, and live
+status so operators can see where problems and opportunities are concentrated.
+
+### 5. Analytics
+
+Analytics explains performance and reliability over time. It compares actual
+behavior with expectations and relates changes to operational events—for
+example, power and hashrate trends, thermal hotspots, recurring failures, and
+repair outcomes.
+
+## Core Principles
+
+### Technician First
+
+Design common workflows for the people doing the work, with fast lookup, clear
+context, and minimal avoidable data entry at the point of action.
+
+### Operational Awareness
+
+Show current condition, scope, urgency, and impact so operators can distinguish
+normal variation, intended downtime, and actionable problems.
+
+### Durable Identity
+
+Follow miners and tracked components through network changes, movement, repair,
+transfer, and retirement without redefining them by mutable attributes.
+
+### Immutable History
+
+Preserve meaningful operational facts. Corrections append or void explicitly;
+they do not silently rewrite or delete the past.
+
+### Maps Explain Location
+
+Use spatial views to reveal where assets, work, capacity, and operational risk
+are concentrated.
+
+### Graphs Explain Trends
+
+Use synchronized time-series views to make change, correlation, and divergence
+from expected performance visible.
+
+### Timelines Explain History
+
+Use ordered events to show what happened, when it happened, and who or what was
+responsible.
+
+### Tables Explain Detail
+
+Use searchable, sortable tables when operators need precise values, comparisons,
+and bulk review.
+
+### Search Everything
+
+Make durable identities, network observations, serials, locations, repairs, and
+components discoverable from a consistent search experience.
+
+### Live by Default
+
+Present the freshest trustworthy operational state by default while making its
+timestamp, source, and staleness clear.
+
+### Explain, Do Not Merely Report
+
+Connect symptoms to history, location, related events, and likely next checks
+instead of displaying isolated measurements.
+
+### Database-Backed Integrity
+
+Enforce critical identity, history, ownership, and concurrency invariants in
+PostgreSQL as well as in application workflows.
+
+### Progressive Complexity
+
+Keep basic inventory, monitoring, and repair work useful without requiring every
+advanced model, while allowing richer structure as operational needs grow.
+
+### Real Operational Problems Before Interesting Technology
+
+Adopt technology only when it makes mining operations safer, clearer, faster,
+or more reliable.
+
+## Mine Map
+
+The Mine Map is a primary operational interface, not an optional visualization.
+It should connect physical layout to live condition, work state, and historical
+context so an operator can move from a site-wide pattern to the relevant group
+or miner.
+
+The current application includes a location map and operational overlays. The
+longer-term Mine Map should support production rooms, racks, shelves, miners,
+repair benches, burn-in racks, quarantine, donor storage, component storage,
+status overlays, temperature and efficiency hotspots, and drill-down into miners
+and groups. Capabilities beyond the implemented location foundations are future
+direction, not present functionality.
+
+## Analytics
+
+Time-series analytics is a core MinerOps capability. It should cover site and
+miner power, hashrate, efficiency, temperature, availability, and expected
+versus actual performance. Graphs should use synchronized event annotations so
+repairs, moves, component changes, configuration changes, and operational events
+can be evaluated against measured behavior.
+
+Operators should be able to compare rooms, racks, models, firmware versions, or
+selected miners over the same interval. Current telemetry collection and status
+views are foundations for this direction; the complete comparative analytics
+experience is not yet implemented.
+
+## Component and Donor Workflows
+
+MinerOps must support the real-world practice of combining working components
+from multiple failed miners to return one miner to service. Meaningful physical
+components need durable identity, transfer history, donor-miner context,
+component genealogy, and explicit movement through repair benches and storage.
+No workflow should silently recreate a component or lose its prior ownership,
+installation, condition, or repair history.
+
+The current minimal component registry, repair-part snapshots, and authoritative
+control-board replacement history are foundations only. Generalized component
+installation, transfer, location, donor, and genealogy workflows remain future
+direction.
+
+## Success Criteria
+
+A technician should quickly answer:
+
+- What is broken?
+- Where is it?
+- Why might it be failing?
+- What repair work has already occurred?
+- What parts or components were used?
+- Did this component come from another miner?
+- What should I do next?
+
+A manager should quickly answer:
+
+- Is the site healthy?
+- Where are the largest operational risks?
+- Where are power, hashrate, or temperature anomalies?
+- Which repairs are delayed?
+- Which rooms, racks, models, or components fail most often?
+- Are reliability and efficiency improving?
+
+## What MinerOps Is
+
+MinerOps is being built as an operational intelligence platform that integrates
+monitoring, repair workflows, durable asset history, component history, spatial
+visualization, analytics, and operational context. It is the shared operational
+record that connects a live observation to the physical asset, its location,
+its history, and the decision it informs.
+
+## What MinerOps Is Not
+
+MinerOps is not intended to become a generic ERP, an accounting platform, a full
+purchasing system, a general warehouse-management system, or a replacement for
+operator judgment. Those systems may integrate with MinerOps later when doing so
+improves operational context without changing MinerOps's core purpose.
+
+## Long-Term Direction
+
+Potential long-term directions include historical map playback, predictive
+maintenance, failure correlation, component genealogy, fleet optimization,
+AI-assisted investigation, and decision support. These are areas for evaluation,
+not delivery commitments. AI should organize evidence, surface relationships,
+and suggest investigations in support of operator judgment; it should not
+replace that judgment.
+
+## Final Guiding Principle
+
+Every feature should solve a real operational problem experienced by technicians, operators, or managers. Operational clarity takes priority over technical novelty.