> Original design reference. The current PHP implementation adds MySQL persistence, server-enforced accounts, Groq workflows and PDF export. See [current implementation](IMPLEMENTATION.md) for the release scope.

# CynarisOS — MVP build specification

## Goal and user
Primary users: Operations lead, sales manager, project contributor, finance reviewer.

Core journey: Opportunity → qualification → project → task completion → invoice draft.

The prototype implements the sample journey in the browser. Production scope includes persistence, validation, identity, authorisation and service integration. Live AI outputs must be explicitly labelled and evaluated.

## Screens
| ID | Screen | Route | Primary behaviour |
|---|---|---|---|
| OS-01 | Overview | `/apps/os/?screen=overview` | Inspect pipeline, tasks, projects and invoice totals. |
| OS-02 | CRM pipeline | `/apps/os/?screen=pipeline` | Create opportunities, search, filter by owner and move stages. |
| OS-03 | Customers | `/apps/os/?screen=customers` | Create a customer and inspect its record. |
| OS-04 | Projects | `/apps/os/?screen=projects` | Create a project and open its task board. |
| OS-05 | Project board | `/apps/os/?screen=board` | Create tasks and move them through a delivery workflow. |
| OS-06 | Invoices | `/apps/os/?screen=invoices` | Create and review invoice drafts without sending. |
| OS-07 | Team | `/apps/os/?screen=team` | Inspect members and proposed role permissions. |
| OS-08 | Workspace settings | `/apps/os/?screen=settings` | Edit workspace details and inspect planned connections. |

## Data requirements
- Customer, Opportunity, Project, Task, InvoiceDraft, Membership.
- Money stored in minor units with an explicit currency. Customer and project relationships use IDs, not repeated names.
- Opportunity stages include discovery/qualified/proposal/won/lost in production. Preserve stage-change history.
- Invoice issuance, tax rules, payment status and numbering need server-side rules. The prototype creates drafts only.

## Proposed API surface
- `GET/POST /customers; GET/PATCH /customers/:id`
- `GET/POST /opportunities; PATCH /opportunities/:id/stage`
- `GET/POST /projects; GET /projects/:id/tasks; POST /projects/:id/tasks`
- `PATCH /tasks/:id; GET/POST /invoice-drafts; GET /invoice-drafts/:id`
- `GET /workspace/members; PATCH /workspace`

All endpoints inherit the workspace-scoping, pagination, validation, error and audit rules in BUILD-HANDOFF.md. Schemas in models.ts are starting contracts, not complete database migrations.

## Required states
- Loading: stable skeleton or progress indicator with an accessible status message.
- Empty: explain the missing record and offer the first useful action.
- Invalid input: inline field error; preserve all valid inputs.
- Service failure: preserve context and offer a safe retry.
- Forbidden or expired access: explain the restriction without leaking record contents.
- Success: update the visible record and dependent summaries, then announce the change.
- Concurrent edit: surface conflict and let the user review the current version.

## Acceptance criteria
- [ ] Create an opportunity, move it to proposal and confirm board totals recalculate.
- [ ] Create a project and task; moving a task to Done updates project completion.
- [ ] Creating a customer validates email and prevents accidental duplicates according to agreed rules.
- [ ] Creating a draft does not send an invoice or initiate payment.
- [ ] Managers see only authorised records; viewers cannot mutate data.
- [ ] Empty columns, no search results, invalid amounts and concurrent edits have clear handling.

## AI implementation boundary
AI calls belong on the server behind task-specific contracts. Log model/prompt version and evaluation outcome without retaining sensitive content unnecessarily. Support cancellation, timeout and a non-AI fallback. Human review remains part of consequential decisions. The current prototype uses deterministic sample logic, not a model.

## Deferred scope
Production integrations, billing, real notifications, operational analytics, advanced collaboration and broad automation are not implied by this prototype. Define them after the core workflow is validated with users.