docs: add product guide

docs/PRODUCT.md

@@ -0,0 +1,377 @@
+# MinerOps Product Guide
+
+## Purpose
+
+MinerOps is intended to become the self-hosted operational system of record for
+cryptocurrency mining operations.
+
+Its primary product position is:
+
+> The self-hosted operating system for cryptocurrency mining operations.
+
+Its supporting statement is:
+
+> Know every miner. Track every repair. Control every rack.
+
+"Operating system" describes a shared operational foundation, not a replacement
+for a computer operating system or miner firmware. MinerOps is intended to
+connect the records and workflows that operators use to understand their fleet,
+maintain equipment, and coordinate work.
+
+"Know every miner" means that each asset should have a durable, understandable
+record. "Track every repair" means that failures, work, parts, tests, and
+outcomes should remain connected to that record. "Control every rack" means
+that operational actions should be available with appropriate context,
+permissions, safeguards, and visibility.
+
+**Current implementation:** MinerOps is an early-stage application. The
+repository contains authentication and role foundations, an Inventory schema
+and backend domain foundation, and existing operational workflows for areas such
+as discovery, repairs, locations, monitoring, and control. These areas are not
+all complete or organized as finished product domains.
+
+**Product direction:** MinerOps should bring these capabilities together around
+one durable operational record while remaining practical for self-hosted use.
+The directions in this guide are not claims that every capability is currently
+implemented.
+
+## Target Users
+
+MinerOps is intended for people responsible for operating and maintaining
+cryptocurrency mining equipment, including:
+
+- Mining farm operators
+- Technicians
+- Operations managers
+- Site administrators
+- Owners managing small or medium fleets
+- Organizations operating multiple rooms or sites
+
+These users need different levels of visibility and control. A technician may
+need fast access to asset history and repair context from the floor. A manager
+may need fleet state, work status, and accountability across teams. A site
+administrator may need configuration and access controls. An owner may need a
+clear view across one facility or several sites.
+
+MinerOps should support those different working contexts without forcing every
+user to navigate the same amount of detail or receive the same operational
+control. Detailed permissions belong to access-control design rather than this
+product guide.
+
+## Problems MinerOps Solves
+
+Mining operations often build their working record from several disconnected
+sources. Asset details may live in spreadsheets, current health in monitoring
+tools, repair notes in informal documents, and physical location knowledge in a
+technician's memory.
+
+Common operational problems include:
+
+- Asset information spread across spreadsheets and ad hoc records.
+- IP addresses changing without a reliable link to the durable asset.
+- Control board replacements changing MAC addresses and confusing identity.
+- Repair and maintenance history being incomplete or difficult to find.
+- Equipment being difficult to locate across rooms, racks, shelves, or storage.
+- Important fleet knowledge existing only in individual technicians' memories.
+- Monitoring and control tools being disconnected from inventory and repair
+  records.
+- Limited audit history for changes and operational actions.
+- Uncertainty about which miners are active, spare, under repair, missing, or
+  retired.
+- Difficulty coordinating safe actions across many miners at once.
+
+MinerOps is intended to reduce this fragmentation. It should help operators
+answer practical questions about what an asset is, where it is, what condition
+it is in, what has happened to it, and what action is appropriate next.
+
+## Product Vision
+
+The long-term product direction is one self-hosted platform connecting:
+
+- Inventory
+- Durable asset identity
+- Network discovery
+- Locations
+- Repairs and work orders
+- Spare parts
+- Monitoring and telemetry
+- Alerts
+- Fleet control
+- Scheduling and automation
+- Electrical and infrastructure records
+- Historical reporting
+- Audit history
+
+These capabilities should reinforce one another. A monitoring alert should
+point to the correct asset. A repair should include the relevant history and
+location. A component replacement should not erase the identity of the miner. A
+fleet action should respect maintenance state and leave an audit record.
+
+This list defines product direction. The repository contains foundations and
+working early-stage workflows in several of these areas, but it does not yet
+provide the complete product described here.
+
+## Product Principles
+
+### Single Source of Truth
+
+Important operational records should have one authoritative home. Other tools
+may contribute observations or consume data, but MinerOps should reduce the
+need to reconcile competing spreadsheets, notes, and dashboards.
+
+A source of truth must be understandable and correctable. It should make the
+current record clear while retaining enough history to explain how that record
+changed.
+
+### Asset Identity Before Network Identity
+
+A miner is not defined by its current IP address or MAC address. Network values
+are mutable observations about an asset, not the asset's durable identity.
+
+MinerOps should preserve a stable internal identity through address changes,
+control board replacements, movement, repair, storage, and retirement. Network
+identity remains important, but it must be associated with the asset rather
+than substituted for it.
+
+### Preserve History
+
+Operationally important changes should remain traceable instead of silently
+overwriting the past. Repairs, locations, network identities, components,
+status changes, and operator actions may all affect how an asset's current state
+is understood.
+
+History should be useful rather than merely accumulated. Records need clear
+timestamps, context, and attribution where appropriate.
+
+### Self-Hosted First
+
+Operators should retain control of their operational data and deployment.
+MinerOps should work as software that an organization can run within its own
+environment without requiring a mandatory hosted subscription.
+
+Self-hosted first does not prohibit internet access, remote access, or external
+integrations. Those capabilities should remain deliberate choices under the
+operator's control.
+
+### Safe by Default
+
+MinerOps may coordinate actions that interrupt mining or affect many devices.
+Potentially disruptive actions require deliberate authorization, clear scope,
+validation, and auditability.
+
+Defaults should favor observation and review over unexpected action. A new
+installation or development environment should not begin issuing broad or
+destructive commands without explicit configuration.
+
+### Practical Operations Over Cryptocurrency Hype
+
+MinerOps is an operations and infrastructure product. Its value comes from
+making assets, repairs, locations, health, and controls easier to understand and
+manage.
+
+It is not a trading, investment, or promotional product. Product decisions
+should be evaluated against operational usefulness rather than cryptocurrency
+trends or speculative features.
+
+### Technician-Friendly
+
+Common workflows should be usable where the work happens. Interfaces should
+support clear scanning, direct actions, and responsive layouts suitable for
+phones and workstations.
+
+Mobile and QR-assisted workflows are appropriate product directions when they
+reduce lookup time or data-entry mistakes. They should complement durable asset
+identity rather than introduce a separate record.
+
+### Progressive Complexity
+
+A small operator should be able to begin with useful inventory, location, and
+repair workflows without configuring every advanced capability. Larger or more
+complex installations should be able to add structure as their needs grow.
+
+Advanced monitoring, automation, infrastructure mapping, and integrations
+should not make the basic operational record harder to use.
+
+### Explicit Human Control
+
+Automation should assist operators without making important decisions
+invisible. Users should understand what will happen, what is happening, and what
+happened afterward.
+
+Automated behavior should expose its scope, conditions, limits, and result. An
+operator must be able to distinguish intentional automation from an unexpected
+system action.
+
+## Core Product Areas
+
+### Inventory and Assets
+
+Inventory provides durable records for miners and related hardware. It connects
+operator-facing Asset IDs, hardware identifiers, lifecycle state, tags, notes,
+and ownership of the asset record without relying on current network values.
+
+### Identity and Discovery
+
+Identity and discovery connect observations from the network to stable assets.
+The product should distinguish current network information from history and
+provide deliberate handling when components or identities change.
+
+### Locations and Infrastructure
+
+Locations and infrastructure describe where equipment is installed or stored
+and how it relates to sites, rooms, racks, shelves, positions, and electrical
+context. Movement should remain understandable over time.
+
+### Repairs and Maintenance
+
+Repairs and maintenance connect problems, diagnostics, work, parts, testing,
+and return-to-service outcomes to the asset. Technicians should be able to see
+prior work before beginning another repair.
+
+### Monitoring and Alerts
+
+Monitoring and alerts explain live and historical operational health. They
+should add observations to the operational record without replacing durable
+inventory, repair, or lifecycle information.
+
+### Fleet Operations
+
+Fleet operations provide permission-controlled actions for individual miners or
+groups. Controls should include enough identity, location, health, and
+maintenance context to reduce avoidable mistakes.
+
+### Scheduling and Automation
+
+Scheduling and automation support repeatable work while preserving safeguards,
+expiry, rollback or recovery behavior where practical, and operator visibility.
+Automation should make coordinated operations more predictable, not less
+accountable.
+
+### Reporting and Audit History
+
+Reporting and audit history help operators understand what changed, who changed
+it, why it changed, and what happened over time. Reports should draw from the
+same operational records used by day-to-day workflows.
+
+## Operational Source of Truth
+
+MinerOps should connect information that is commonly separated:
+
+- Asset identity
+- Network identity
+- Physical location
+- Repair status
+- Operational status
+- Historical changes
+
+These are related views of one operational asset, not independent records to be
+manually reconciled. Current status should remain distinct from lifecycle,
+repair, and location state so that one value does not erase important context.
+
+A miner should remain understandable throughout its lifecycle: initial entry,
+deployment, discovery, movement, component replacement, failure, repair,
+testing, storage, redeployment, and retirement. Operators should be able to
+follow that history even when the miner's address, control board, rack, or
+condition changes.
+
+The source-of-truth role also requires correction. Authorized users should be
+able to fix inaccurate records without destroying meaningful history or hiding
+who made the change.
+
+## Self-Hosted Philosophy
+
+Self-hosting matters because mining operations depend on local equipment,
+segmented networks, and operational data that may need to remain under direct
+organizational control.
+
+A self-hosted MinerOps deployment should support:
+
+- Operational control over configuration and availability.
+- Ownership of asset, repair, telemetry, and audit data.
+- Access to equipment on local networks where appropriate.
+- Independence from mandatory hosted subscriptions.
+- Operation in restricted or segmented environments.
+- Backup, restore, and migration under the operator's control.
+
+Self-hosted does not mean isolated. Optional remote access, manufacturer
+interfaces, reporting systems, or other integrations may be valuable. They
+should not make a hosted third party the mandatory owner of the operational
+record.
+
+## Safety and Control
+
+MinerOps may eventually perform actions capable of disrupting individual miners
+or a significant part of a fleet. Safety is therefore a product behavior, not
+only an implementation concern.
+
+Product expectations include:
+
+- Role and permission enforcement.
+- Clear confirmation for destructive or broad actions.
+- Dry-run or preview behavior where practical.
+- Staggering, rate limits, and scope limits for bulk actions.
+- Commands that expire rather than remain indefinitely actionable.
+- Audit history for requested actions and outcomes.
+- Awareness of maintenance state and intentionally offline equipment.
+- Safe defaults in development and new installations.
+
+The interface should communicate the intended target, scope, and likely impact
+before an action is accepted. Afterward, the operator should be able to see
+whether the action ran, partially succeeded, failed, expired, or was cancelled.
+
+Automation does not remove the need for authorization or visibility. The
+broader the potential effect, the more explicit the safeguards should be.
+
+## What MinerOps Is Not
+
+MinerOps is not intended to be:
+
+- A cryptocurrency exchange
+- A wallet
+- A trading platform
+- An investment dashboard
+- A hosted mining provider
+- A replacement for manufacturer firmware
+- A general-purpose data centre management suite
+- A tool that hides unsafe automation from operators
+- A promotional cryptocurrency project
+
+MinerOps may integrate with manufacturer interfaces, accounting systems,
+monitoring tools, or other external services when those integrations improve
+mining operations. Integration does not change the product's core purpose: a
+self-hosted operational system of record for mining assets and workflows.
+
+## Measures of Success
+
+MinerOps is succeeding when:
+
+- Operators can identify and locate any recorded miner quickly.
+- A miner's history remains understandable after IP, MAC, control board, or
+  location changes.
+- Technicians can see prior failures and repairs before starting work.
+- Managers can understand fleet state without reconciling several spreadsheets.
+- Bulk actions are controlled, visible, and auditable.
+- Operational data can be backed up, restored, and migrated.
+- The system remains useful for both small and larger installations.
+- New features strengthen a coherent operational record instead of creating
+  another disconnected tool.
+
+These are practical outcomes rather than numerical targets. Measures should be
+refined using real operator workflows and evidence as the product develops.
+
+## Product Decision Test
+
+A proposed feature should normally answer yes to one or more of these questions:
+
+- Does it help identify a miner or related asset?
+- Does it help locate equipment?
+- Does it improve understanding of current or historical condition?
+- Does it support repair, maintenance, or return-to-service work?
+- Does it improve safe monitoring or control?
+- Does it preserve meaningful operational history?
+- Does it reduce fragmented or duplicated records?
+- Does it remain consistent with self-hosting and operator control?
+
+A technically interesting feature is not automatically a MinerOps feature. It
+should improve cryptocurrency mining operations and fit the product's
+source-of-truth role.