This document is the canonical public-docs reference for AI-assisted StratoFusion work. It consolidates the former docs/ai/* workflow files into the public/docs/ documentation tree.
For live agent instructions, the root AGENTS.md file remains the execution contract. This document keeps the same guidance available through /dev/docs.
Role And Context
AI agents working in this repository act as senior software architects and engineers on StratoFusion, a SaaS platform that unifies cloud storage providers such as Google Drive, OneDrive, and Dropbox into a single UI.
Data-plane operations execute through the rclone worker in the current VM Compose stack. Stopped Fly.io apps preserve the legacy deployment for approved recovery only.
Local development is Windows 11.
Do not use or assume WSL.
Keep architecture provider-agnostic and interface-first.
Environment And Tooling
Shells
Use PowerShell for normal Codex commands, git, PNPM, Node, tests, file inspection, and repo work on Windows.
Use Git Bash only for .sh scripts or commands that require POSIX shell behavior.
Invoke Git Bash explicitly with C:\Program Files\Git\bin\bash.exe.
Never invoke bare bash.
Use Windows paths in PowerShell and /c/... paths only inside Git Bash.
Package Management
PNPM is mandatory.
Run pnpm env:guard before repo shell workflows.
Shell scripts must remain compatible with Git Bash.
Architecture Standards
Core Principles
UI components render only.
Business behavior belongs in domain modules, services, ports, adapters, or hooks.
Provider-specific IDs, raw paths, rate-limit shapes, and response formats must not leak into UI components.
Depend on interfaces and canonical models, not concrete provider implementations.
Prefer deep modules with stable interfaces over shallow helper sprawl.
Keep files under 500 LOC.
Provider Contract
When adding or changing provider behavior:
Start from the shared provider interface or an explicit port.
Translate provider outputs into canonical models such as FileItem, FolderItem, and PathRef.
Treat (provider, account, resource) as the ownership and behavior boundary.
Keep provider quirks inside adapters, provider services, or domain services.
Add deterministic tests with external systems mocked behind interfaces.
Rclone Safety
Data safety is the highest-priority constraint for transfer work.
Always state source, destination, direction, and flags before launch.
Manual rclone commands default to --dry-run unless the user explicitly approves otherwise.
Delete, purge, overwrite, move, sync-delete, and cleanup semantics require explicit approval or a clear task mandate.
Copy, move, backup, one-way sync, two-way sync, and bisync are different workflows. Do not collapse their semantics.
Scrub rclone configs, OAuth tokens, API keys, database URLs, and secrets from logs.
Launch paths must validate auth, provider quota, transfer quota, conflicts, cancellation, retry, timeout, and reconciliation behavior before expensive work starts.
Ubiquitous Language
Term
StratoFusion meaning
Notes
Provider
A cloud storage backend such as Google Drive, OneDrive, Dropbox, Box, pCloud, or Jupiter.
Hide provider-specific API behavior behind stable boundaries.
Account
A user's connected identity within a provider.
Never assume one account per provider.
Resource
A provider-backed object StratoFusion can address.
Normalize resources before using them as business truth.
FileItem
Canonical file model.
Hides provider IDs, MIME quirks, timestamps, and download behavior.
FolderItem
Canonical folder model.
Handles provider differences such as duplicate names and empty-folder behavior.
PathRef
Canonical reference to a location or item path.
Do not treat raw provider paths as UI business truth.
Service
Domain or application module that owns a capability.
UI calls service-facing interfaces or hooks.
Adapter
Translation layer from provider shape to canonical shape.
Provider conditionals live here or in provider services.
Port
Stable interface for an outside capability.
Use ports when behavior must be testable or replaceable.
Operation
Concrete execution unit, often rclone-backed.
Operations are not the same as scheduled jobs.
Job
Durable backup or sync intent with schedule, sources, destination, and child operations.
Reconciliation handles partial launches and terminal children.
Transfer
General movement or comparison work across providers or accounts.
Always name source, destination, direction, and destructive flags.
Copy
Non-destructive transfer that leaves the source intact.
Single-file rclone copy uses copyto when a target filename is required.
Move
Transfer that removes or relocates the source after copying.
Treat as potentially destructive.
Backup
One-way preservation workflow from selected sources to a destination.
Default to non-destructive behavior and explicit conflict handling.
Sync
Ongoing convergence workflow, one-way or two-way.
Two-way/bisync has initialization and conflict semantics.
Data plane
Execution layer for file bytes and large transfers.
Rclone worker in the production VM Compose stack; stopped Fly.io recovery apps.
Control plane
Next.js/API/domain layer for validation, ID resolution, auth, quotas, and state.
Prepares safe execution inputs.
Provider quota
Cloud-provider storage or API capacity limit.
Distinguish from StratoFusion transfer quotas.
Transfer quota
StratoFusion plan or time-window transfer allowance.
Enforce before launching expensive work.
Conflict resolution
Destination collision policy.
Keep policies canonical and translate at provider/rclone boundaries.
Feature Workflow
0. Load AI Skills
Repo-local agent skills live under docs/ai-skills/. Start with
docs/ai-skills/INDEX.md, then load the smallest relevant skill set for the
task. Use docs/ai-skills/01-architecture.md for every non-trivial change, and
add domain skills for provider, rclone/Fly, API, UI, testing, OAuth, billing,
deployment, AI Search, RAG, code review, or prompt creation work.
The skills summarize the canonical docs. If a skill and this public protocol
ever drift, update the skill or follow this protocol and AGENTS.md.
Optional Agent Delivery Harness
When a task explicitly opts into Agent Delivery Harness v1, also follow
AGENT_DELIVERY_HARNESS.md. The harness adds a
human-confirmed risk tier, isolated task lease, bounded review/repair cycle,
optional private evidence, and human-ready handoff. It does not authorize
unattended writing, merging, deployment, production access, external
communication, or repository-setting changes.
1. Read Context
Read AGENTS.md, README.md, and the relevant docs under public/docs/.