docs

openspec/changes/define-platform-foundation/specs/control-plane-core/spec.md

@@ -0,0 +1,29 @@
+## ADDED Requirements
+
+### Requirement: aiNAS control plane as product system of record
+The system SHALL define an aiNAS-owned control plane as the authoritative home for product-level domain concepts.
+
+#### Scenario: Product semantics require persistence
+- **WHEN** aiNAS needs to represent devices, workspaces, storage sources, shares, mount profiles, policies, or audit history
+- **THEN** the planning artifacts MUST place those concepts inside the aiNAS control-plane domain model
+
+### Requirement: High-level domain contracts
+The platform SHALL define a first high-level contract map for core entities and API categories before implementation proceeds.
+
+#### Scenario: Future implementation work needs a stable conceptual frame
+- **WHEN** engineers start implementing the control plane
+- **THEN** the planning artifacts MUST already identify the first core entities and the first API categories those entities imply
+
+### Requirement: Standalone service posture
+The control plane SHALL remain architecturally standalone even if it is temporarily packaged or surfaced through Nextcloud-compatible mechanisms.
+
+#### Scenario: aiNAS backend is consumed by multiple surfaces
+- **WHEN** a standalone web app, Nextcloud shell, or future device client needs backend behavior
+- **THEN** the design MUST treat the control plane as a reusable aiNAS service rather than as logic conceptually trapped inside the Nextcloud app model
+
+### Requirement: Single modular backend first
+The platform SHALL prefer one modular backend service before splitting the control plane into multiple distributed services.
+
+#### Scenario: Engineers plan service topology
+- **WHEN** the first real control-plane backend is planned
+- **THEN** the default architecture MUST be one service with explicit internal modules rather than many microservices

openspec/changes/define-platform-foundation/specs/device-access-layer/spec.md

@@ -0,0 +1,22 @@
+## ADDED Requirements
+
+### Requirement: Distinguish cloud-drive access from true remote mounts
+The platform SHALL explicitly distinguish between cloud-drive style access and true remote mount behavior.
+
+#### Scenario: Device access strategy is discussed
+- **WHEN** aiNAS plans device-native access on macOS or mobile
+- **THEN** the planning artifacts MUST state whether the capability is based on cloud-drive style client behavior, true remote mounts, or both
+
+### Requirement: Defer custom native agent work until justified
+The platform SHALL not require a custom device-native agent for the first backend and control-plane planning unless true remote mount orchestration is confirmed as a near-term requirement.
+
+#### Scenario: Delivery sequencing is chosen
+- **WHEN** implementation order is planned
+- **THEN** the design MUST allow heavy reuse of Nextcloud client references before requiring a custom native device daemon
+
+### Requirement: Keep future device agent possible
+The architecture SHALL preserve a clear boundary where a future aiNAS-owned device access layer can be introduced without rewriting the control plane.
+
+#### Scenario: Product later adds login-time mounts or stronger native behavior
+- **WHEN** aiNAS decides to add explicit mount orchestration or device-native workflows
+- **THEN** the design MUST place that behavior in a device access layer separate from the core control-plane domain

openspec/changes/define-platform-foundation/specs/nextcloud-substrate/spec.md

@@ -0,0 +1,29 @@
+## ADDED Requirements
+
+### Requirement: Nextcloud substrate boundary
+The system SHALL explicitly define which storage, sharing, and client primitives aiNAS adopts from Nextcloud and which concerns remain aiNAS-owned.
+
+#### Scenario: Product planning references Nextcloud capabilities
+- **WHEN** aiNAS decides whether to build or reuse a capability
+- **THEN** the planning artifacts MUST classify the capability as either Nextcloud substrate, aiNAS-owned logic, or a later optional fork/reference path
+
+### Requirement: Reuse external storage backends
+The platform SHALL treat Nextcloud external storage support as the first candidate substrate for connecting backend storage systems.
+
+#### Scenario: aiNAS selects initial backend storage types
+- **WHEN** aiNAS chooses the first storage backends to support
+- **THEN** the plan MUST assume reuse of Nextcloud-supported external storage backends before proposing custom storage ingestion infrastructure
+
+### Requirement: Reuse desktop and mobile references first
+The platform SHALL treat the public Nextcloud desktop and iOS clients as the first reference implementations for cloud-drive style access before planning fully custom clients.
+
+#### Scenario: aiNAS evaluates native device access
+- **WHEN** the product needs Finder-style or mobile file access
+- **THEN** the plan MUST document whether Nextcloud clients are being used directly, referenced, branded later, or intentionally replaced
+
+### Requirement: Keep Nextcloud as substrate, not system of record
+The platform SHALL not let Nextcloud become the long-term system of record for aiNAS-specific product semantics.
+
+#### Scenario: New product concept is introduced
+- **WHEN** aiNAS introduces workspaces, devices, policies, mount profiles, or similar product concepts
+- **THEN** the design MUST model those concepts in aiNAS-owned contracts rather than relying on implicit Nextcloud-only representations

openspec/changes/define-platform-foundation/specs/standalone-control-plane-web/spec.md

@@ -0,0 +1,22 @@
+## ADDED Requirements
+
+### Requirement: Standalone aiNAS web surface
+The platform SHALL plan for a standalone web control-plane surface outside Nextcloud.
+
+#### Scenario: Product UI expands beyond an embedded shell
+- **WHEN** aiNAS needs an admin or product control interface that is larger than a thin Nextcloud page
+- **THEN** the plan MUST place that interface in an aiNAS-owned standalone web application
+
+### Requirement: Web UI consumes aiNAS API
+The standalone web application SHALL be designed to consume aiNAS-owned backend contracts rather than Nextcloud internals directly.
+
+#### Scenario: Web product feature requires backend data
+- **WHEN** the standalone web surface needs workspaces, devices, shares, or policies
+- **THEN** it MUST obtain those concepts through the aiNAS control-plane API design rather than by binding directly to Nextcloud internal models
+
+### Requirement: Preserve Nextcloud shell as adapter
+The presence of a standalone web app SHALL not remove the need for the thin Nextcloud shell as an adapter and embedded entry surface.
+
+#### Scenario: aiNAS still needs a presence inside Nextcloud
+- **WHEN** the broader product grows outside the Nextcloud UI
+- **THEN** the shell app MUST remain conceptually limited to integration and entry-point responsibilities rather than absorbing the full standalone product