# RightOS + RightFlow — Concept and Usage Guide - date: 2026-07-13 - languages: EN (this file) · [JA](./RIGHTOS_RIGHTFLOW_CONCEPT_GUIDE.ja.md) · [zh-CN](./RIGHTOS_RIGHTFLOW_CONCEPT_GUIDE.zh-CN.md) · [zh-TW](./RIGHTOS_RIGHTFLOW_CONCEPT_GUIDE.zh-TW.md) - terminology: [Terminology](./RIGHTOS_RIGHTFLOW_TERMINOLOGY.md) - boundaries: [Architectural Scope](./RIGHTOS_RIGHTFLOW_ARCHITECTURAL_SCOPE.md) - when to use: [Decision Guide](./RIGHTOS_RIGHTFLOW_DECISION_GUIDE.md) - Web: https://rightos.i-s3.com/software/rightos/docs/concept **Product names `RightOS` and `RightFlow` stay in English in every locale.** --- ## In one minute | Layer | Question | Owns | | --- | --- | --- | | **RightOS** | What may be done? | Rights, policy, proof | | **RightFlow** | What should happen next? | Tasks, order, assignment, coordination | | **Your execution system** | How is it actually done? | Robots, humans, AI, vehicles, software | RightOS and RightFlow do **not** try to centrally control every participant. They support **asynchronous cooperation** across **independent actors, authorities, and execution systems**. ```mermaid flowchart TD R["RightOS
What may be done?"] F["RightFlow
What should happen next?"] E["Your system
How is it done?"] R --> F --> E ``` --- ## How the separation emerged 1. A person may have a temporary right to wait at a particular place. 2. A machine-verifiable system can represent and verify that right. 3. The same idea can apply to access, use, reservation, or execution rights. 4. When many actors have work to do, rights alone are not enough. 5. Actors may need order, assignment, delegation, reassignment, or task exchange. 6. Coordination must not silently manufacture authority. 7. Therefore **rights authority** and **coordination** are separated → **RightOS + RightFlow**. --- ## 1. What is RightOS? RightOS is a **rights / policy / proof** layer. It helps answer: **what may this actor do?** In practice it issues, holds, verifies, consumes, expires, transfers, or cancels **rights** (often presented as QR “Right Tokens”) without requiring end-user names, phone numbers, or birthdates. It is **not** a taxi or ride-hailing product. It does not arrange vehicles, set fares, assign drivers, or broker dispatch. **Supported today (production service):** token issue / verify / use / cancel / transfer, location policies, webhooks, billing, Console, SDKs, MCP — see [RightOS Quickstart](https://rightos.i-s3.com/software/rightos/docs/quickstart). --- ## 2. What is RightFlow? RightFlow is a **coordination** layer. It helps answer: **what should happen next?** It tracks tasks, capabilities, assignment proposals (assign / reassign / swap), dependencies, and execution-facing state among independent actors. It is **not** a marketplace, fleet manager, robot controller, or payment system. It proposes coordination; it does not mint rights. **Supported today (shipped API + npm packages):** tasks, actors, proposals, safety-event reconcile / break-glass paths, OpenAPI, thin TS client, MCP — see [RightFlow docs](https://rightos.i-s3.com/software/rightflow/docs). --- ## 3. Why are they separate? Because **permission** and **work order** can change on different clocks. - A right can expire or be revoked while a task is still assigned. - An optimizer can propose a better assignment without owning authority. - Two organizations can disagree; the system should not pretend they agree. If one local system already owns permission, scheduling, and execution under one authority, you usually do **not** need this separation. See §13 and the [Decision Guide](./RIGHTOS_RIGHTFLOW_DECISION_GUIDE.md). --- ## 4. What is an actor? An **actor** is a participant that can hold capabilities and take on tasks. An actor may be a person, AI agent, robot, vehicle, software service, or organization. RightFlow does not require a fixed “human / robot / AI” enum. Kind is secondary; **capability** and **authority** matter more. --- ## 5. What is a capability? A **capability** is a string label for what an actor can do (example: `carry.light`). Capabilities help proposals check fit. They are not the same as rights. Having a capability does not grant a RightOS token. --- ## 6. What is a right? A **right** is authorization that something **may** be done — often time-bounded, place-bounded, transferable under policy, and machine-verifiable. RightOS owns the lifecycle of rights. RightFlow may *refer* to required rights; it must not rewrite them. --- ## 7. What is a task? A **task** (FlowTask) is a unit of work that should happen: state, required capabilities, optional required rights, dependencies, assignee, schedule window, optional spatial requirement. Tasks can outlive a single API request. That is intentional for asynchronous cooperation. --- ## 8. What is a coordination proposal? A **proposal** is an uncommitted suggestion to assign, reassign, or swap tasks. Accepting a proposal updates coordination state. Where required rights are attached, RightOS is consulted as a **read-only gate**. A proposal never creates a new right by itself. --- ## 9. What happens when rights change? Rights can expire, revoke, or leave their validity window **independently** of assignment. **Boundary contract:** assignment is not permanent authorization. Where policy requires it, execution systems must re-check “may” before acting. Safety events can also interrupt normal coordination; reconcile afterward (see ADR-0028). Emergency stop does not wait for ordinary proposal flow. --- ## 10. What remains outside the system? Outside RightOS + RightFlow: - Motor control, navigation, SLAM, collision avoidance loops - Emergency stop and sub-second safety - Vendor robot / vehicle controllers - Human judgment and clinical interrupt paths - Marketplaces, bidding, settlement - Vehicle dispatch / fare / driver assignment Those belong to **execution systems** or other products. --- ## 11. When should I use RightOS only? Use **RightOS only** when you mainly need to issue, verify, consume, expire, revoke, transfer, or prove rights — for example retail queue, clinic wait, EV charger order, event entry, package pickup — without a multi-actor assignment protocol. --- ## 12. When should I use RightOS + RightFlow? Use **both** when independent actors must coordinate tasks while authority stays separately controlled: - multiple operators or vendors - rights that change while work is still open - third-party optimizers that must not mint authority - human / AI / robot / facility systems cooperating asynchronously --- ## 13. When should I use neither? Do **not** add RightOS + RightFlow merely because you have a robot, an AI agent, a queue, or a permission flag. Prefer a simpler local design when: - device-local mutex / lock - motor or continuous vehicle control - collision avoidance or e-stop paths - single authority already owns permission + workflow + execution - simple local schedulers with one shared lifecycle For fit questions, use the [Decision Guide](./RIGHTOS_RIGHTFLOW_DECISION_GUIDE.md). --- ## 14. Example scenarios | Label | Meaning | | --- | --- | | Design pattern | Illustrates how the layers fit together | | Available today | Matches shipped APIs and documented boundaries | ### Waiting and pickup — *available today (RightOS)* A person holds a temporary right at a pickup point and proves it without unnecessary personal data. ### Lightweight logistics — *design pattern / available today (both)* Two delivery actors have different tasks. One is delayed. RightFlow proposes reassignment. RightOS checks whether the replacement may act. ### Multi-vendor robots — *design pattern* Robots from different operators share a facility. They coordinate tasks without one manufacturer becoming the universal authority. ```mermaid flowchart LR FA[Facility authority] RA[Robot operator A] RB[Robot operator B] AI[AI coordinator] HO[Human operator] FA --- RF[Rights + coordination] RA --- RF RB --- RF AI --- RF HO --- RF ``` ### Hospital transport — *design pattern* Pharmacy, facility access, robot operators, AI coordinator, and staff cooperate. Each keeps its own permissions; RightFlow coordinates order; execution stays local. ### Loading docks — *design pattern* Vehicles need a spatial resource. Rights and task order can change independently. ### EV charging coordination — *design pattern / available today* RightOS supports fair charger-queue rights. RightFlow matters when actors reassign charging *tasks* without changing what the charger rights allow. ### AI agent delegation — *available today (coordination + rights gate)* Agent A holds a task in the coordination sense. A proposal asks Agent B to take related work. RightOS verifies required rights where attached. Named “delegation” as a separate API kind is not required in v0.1; reassignment covers the pattern. ### Human / AI / robot workflow — *design pattern* Human prepares, robot transports, AI coordinates dependencies, facility system gates access — same abstract model across actor kinds. ### Software systems — *design pattern* Two services coordinate long-lived tasks. An optimizer recommends; authorization remains independently verifiable. --- ## 15. Finding a fit for your system RightOS and RightFlow are **actor-neutral**. Start from: > Which independent actors must cooperate without sharing one authority? ### Checklist 1. Who are the independent actors? 2. Who controls each permission? 3. Can permissions change while a task still exists? 4. Can another actor take over a task? 5. Can an optimizer propose actions without owning authority? 6. Does execution belong to another system? 7. Do tasks survive longer than one API request? 8. Are multiple organizations involved? If several answers are **yes**, RightOS + RightFlow may fit. --- ## 16. Next steps | Step | Where | | --- | --- | | Concept page | https://rightos.i-s3.com/software/rightos/docs/concept | | Decide fit | [Decision Guide](./RIGHTOS_RIGHTFLOW_DECISION_GUIDE.md) | | RightOS | [Quickstart](https://rightos.i-s3.com/software/rightos/docs/quickstart) · [API docs](https://rightos.i-s3.com/software/rightos/docs) · [OpenAPI](https://rightos.i-s3.com/openapi.json) | | RightFlow | [Overview](https://rightos.i-s3.com/software/rightflow) · [**Facility Handoff Lab (live)**](https://rightos.i-s3.com/software/rightflow/lab) · [API docs](https://rightos.i-s3.com/software/rightflow/docs) · [OpenAPI](https://rightos.i-s3.com/rightflow-openapi.json) | | SDKs | `@i-s3/rightos`, `rightos-sdk` (Python), `@i-s3/rightflow`, thin clients under `/sdk/` | | MCP | `@i-s3/rightos-mcp`, `@i-s3/rightflow-mcp` | | Boundaries | [Architectural Scope](./RIGHTOS_RIGHTFLOW_ARCHITECTURAL_SCOPE.md) | | Deep essay | [Assignment Is Not Authority](./RIGHTOS_RIGHTFLOW_ESSAY.md) · [JA](./RIGHTOS_RIGHTFLOW_ESSAY.ja.md) · [zh-CN](./RIGHTOS_RIGHTFLOW_ESSAY.zh-CN.md) · [zh-TW](./RIGHTOS_RIGHTFLOW_ESSAY.zh-TW.md) | Try without a sales call: demo key `rk_demo_00000000000000000000`, free signup (instant API key; 30-day Business-class trial), or the live **[Facility Handoff Lab](https://rightos.i-s3.com/software/rightflow/lab)** (Assignment is not authority). --- ## Boundary contracts 1. **Assignment is not authority** — re-check rights before execution when policy requires. 2. **Optimization ≠ authority** — a good plan is not automatically allowed. 3. **Safety may bypass normal coordination** — act locally; reconcile later. 4. **Authorities may disagree** — disagreement stays visible; it is not silent success. --- ## Working with agents and tools - An `assigned` or accepted proposal is coordination state, not proof of permission. - RightOS answers **MAY**. RightFlow answers **NEXT**. Execution systems answer **HOW**. - Use **RightOS + RightFlow** together when independent actors reassign work under separately revocable rights. - MCP packages stay separate on purpose: `@i-s3/rightos-mcp` (rights) and `@i-s3/rightflow-mcp` (coordination). - Agent-to-agent messaging (A2A or similar) handles dialogue. Rights checks stay in RightOS; shared task state stays in RightFlow. - Hosted v0.1 uses one organization API key. Marketplace, vehicle dispatch, motor control, and cross-organization authority federation are outside the shipped OpenAPI. - Outcome codes A–E in the Decision Guide help decide whether the architecture fits before you build.