> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kayanos.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Welcome to KayanOS

> Understand how KayanOS connects public-service records, accountable work, evidence, decisions, and controlled access in one workspace.

KayanOS is a governed workspace for running a service, not just collecting a form. It brings together the service record, the people responsible for it, the task that must happen next, the evidence that supports a decision, and the access rules that keep each part visible only to the right people.

This guide uses a **Citizen Services Directorate** training scenario. A citizen request is registered as `CSR-2026-00042`, reviewed by the service team, scheduled for an inspection when needed, supported by controlled evidence, and closed with a recorded outcome. Use the scenario to understand the design pattern; replace its fields, roles, and policy rules with your organization’s approved design.

## Goal

By the end of this guide, you should be able to describe one service from intake to closure and identify:

* the record that remains the source of truth;
* the people who can view, create, update, decide, or share it;
* the task, event, file, and communication that support the record without duplicating it; and
* the safe order for building and testing the service.

## What belongs where

The names in the sidebar are not interchangeable. Use the smallest object that carries the information and responsibility you need.

| KayanOS object          | Use it for                                                                      | Do not use it as                                                            |
| ----------------------- | ------------------------------------------------------------------------------- | --------------------------------------------------------------------------- |
| Organization and member | The current workplace and the staff identity working in it                      | A substitute for a citizen, applicant, or external contact record           |
| Application and section | A discoverable home for related entities, forms, and dashboards                 | A permission grant by itself                                                |
| Entity and record       | Durable operational facts: a request, inspection, permit, decision, or project  | A temporary form screen or a chat transcript                                |
| Form and form session   | Guided intake or a controlled staff interaction                                 | The only copy of a decision that must remain searchable on a record         |
| Task                    | A named piece of accountable work with an owner, assignee, due date, and status | A replacement for the service record’s lifecycle                            |
| Calendar event          | A scheduled meeting, inspection, or review window                               | Proof that a decision was made or that an external invitation was delivered |
| Library file or folder  | Evidence, approved templates, reports, photographs, and issued documents        | A public link that bypasses access rules                                    |
| Notification            | A prompt to open the relevant work                                              | The underlying evidence or decision itself                                  |
| Dashboard               | A view of approved data for operational awareness                               | The system of record for an individual case                                 |

For example, the request `CSR-2026-00042` stores the applicant’s service data, current status, owner, serial reference, and final outcome. Its inspection is a related record because it has its own date, place, inspector, findings, and files. A task tells a Registry Officer to check completeness. A calendar event reserves the inspection time. The report is stored in the Library or attached through the approved record field. A notification takes the responsible person back to the relevant task or record.

## Follow one request from intake to closure

The following sequence is deliberately small. Build and test it before introducing more forms, dashboards, document output, or automations.

1. **Register the request.** A citizen or staff member submits an intake form. KayanOS creates or updates the service record and gives it the agreed human reference, such as `CSR-2026-00042`.
2. **Check completeness.** A Registry Officer opens the record, verifies category, contact path, location, required evidence, and any validation messages. The officer records the outcome on the record and completes or returns the related task.
3. **Assign accountable work.** The Service Manager becomes the record owner or assigns an owner according to the service policy. A task can be assigned to the person doing the next action; contributors and informed members are added only when they need a real role in the work.
4. **Schedule service activity.** If a field visit is required, schedule an event with internal attendees, the correct timezone, location or meeting room, agenda, and expected next steps. A calendar event coordinates time; it does not replace the inspection record.
5. **Capture findings and evidence.** The Field Inspector creates or updates the related inspection record, uploads evidence to a controlled location, and adds a concise operational note. Keep the final factual finding on the record rather than only in chat or email.
6. **Review and decide.** The authorized reviewer checks the record, evidence, and applicable policy. If a formal signature or controlled form decision is required, use the configured form/signature path; do not treat a task checkbox as formal approval evidence.
7. **Communicate carefully.** An authorized mailbox user prepares a message only after verifying the account, sender identity, recipient, serial reference, language, and attachments. A saved draft is not delivery; a send result can still report a failure or partial delivery.
8. **Close and measure.** Update the approved status, record the outcome and next obligation, complete remaining tasks, and review the workload in a dashboard. The record, not a dashboard total, remains the source of truth for the individual request.

## Access is part of the service design

A page being visible does not mean every action on it is available. KayanOS evaluates access through assigned verbs and scopes. In practical terms, ask four questions before publishing a service:

1. **Which resource is protected?** For example, service requests, inspections, events, files, forms, or roles.
2. **Which action is needed?** Listing a queue, opening a record, creating a task, updating a finding, deleting an event, or sharing a file are different actions.
3. **Which scope applies?** A member may work only in their service center, node, form, or another approved scope.
4. **How will you test it?** Test with an authorized non-owner member as well as a manager or administrator. Confirm both the allowed action and the action that must remain denied.

Do not solve an isolated access problem by assigning a broad organization-wide role. Give the smallest practical verb and scope, then test the complete path: navigation, list, open, create, update, download, share, and delete where relevant.

## A reliable first-week sequence

Use this sequence for a first service release. Each step has a concrete output that the service owner can review.

1. Write the service outcome, requester, accountable team, and completion rule in plain language.
2. Create the primary entity and only the fields needed to receive, assign, decide, communicate, and report on that outcome.
3. Define a small status lifecycle. For every status, name the accountable role, required evidence, permitted next status, and citizen-facing meaning if applicable.
4. Design roles and scopes before publishing a form. Test a Registry Officer, Service Manager, Field Inspector, Records Officer, and Administrator against the actions each needs.
5. Build the intake form and one internal entry path. Submit a controlled non-production request and follow it through each handoff.
6. Add tasks, calendar activity, Library evidence, notifications, documents, or automations only when the record path and access test are understood.
7. Capture the test result: what was created, who could see it, which status changed, what notification was received, and what remains intentionally unavailable.

## Expected result

You have a small, reviewable service path in which every person can answer: “What is the request? Who owns the next action? What evidence supports the current status? What happens next?” If the answer requires searching across an unrelated spreadsheet, chat thread, and inbox, refine the record model before scaling the service.

## Safe testing

Use an organization-approved non-production workspace or record. Use synthetic citizen details and policy-approved internal recipients. Do not use a training record to issue a real decision, send a citizen-facing message, publish a public form, or broaden production access. After testing, record the observed result and remove temporary permissions or data according to your organization’s retention process.

## Common mistakes

| Symptom                                               | Likely design issue                                                       | Safer response                                                             |
| ----------------------------------------------------- | ------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
| Staff cannot find the current truth                   | Facts were split between a form, chat, and files without a primary record | Name the primary entity and link supporting objects back to it             |
| A member sees a page but cannot save                  | The member lacks the required verb or the record is outside their scope   | Review the resource, action, and scope instead of granting a broad role    |
| A calendar event is treated as inspection evidence    | Time coordination was confused with the inspection outcome                | Store findings and evidence on the related inspection/request record       |
| A completed task is treated as an authorized decision | Task completion was confused with an approval or signature                | Use the configured status, action, and signature workflow for the decision |
| A draft email is assumed delivered                    | The message was saved but not sent, or delivery later failed              | Review sender, recipients, attachments, and the delivery result            |

## Related guides

* Learn the vocabulary behind this model in [Core concepts](/start/core-concepts).
* Build least-privilege access in [Roles and access](/start/roles-and-access).
* Follow the full service scenario in [Explore an example workspace](/start/example-workspace).
* Design the record before implementation in [Plan an app before building](/build/plan-an-app).
* Configure the request reference in [Serial IDs](/build/serial-ids) and derived values in [Calculated fields](/build/calculated-fields).

![KayanOS home workspace](https://kayanos.app/docs-images/en/start/overview.png)