A tour of the workspace

Draft for review

The workspace is the web app you sign in to. This page goes through its sidebar from top to bottom. For each screen it says what the screen is for and which page of this guide covers it in full. Read it once with the demo company open and you will know where everything else in the guide lives.

This guide describes the workspace as it works today on the golive branch. What is not possible yet is listed at the end.

Signing in#

1. Open the workspace address in a browser. ok demo serve prints it on its Workspace line (for example http://127.0.0.1:8080). You see the sign-in page: "Sign in with the token an admin gave you."
2. Paste your token in the Token field and choose Sign in. In the demo, ok demo serve prints one token per person (see Quickstart). Anywhere else, an admin issues you one from the People page.

You land on Threads. There is one exception: an admin of a brand-new company with no modules yet lands on Setup. If you open an address the workspace does not know, it also takes you to Threads.

The sidebar at a glance#

The sidebar has the same shape for everyone, but not everyone sees every item. Here is what Ada (the admin) and Maya (the support lead) see in the demo:

Three things change from person to person:

• Admin-only items. People, Modules and Setup appear only for admins. If someone who is not an admin opens one of these addresses anyway, the page says so: "Issuing tokens for others is for admins.", "Only admins enable and configure modules.", "Only admins set up the company."
• Module pages. The sections between Curation and Company come from the modules your company has enabled (a module is a packaged part of the company, such as Sales or Support; see Modules). You see a page only if you may read at least one of the collections it shows. Being an admin does not change this.
• Governance tabs. The Audit tab appears for admins only. Maya opening /governance/audit sees "The audit log is for admins."

The item you are on is highlighted, and the browser tab reads "page · OrchKernel" (for example "Inbox · OrchKernel").

Inbox#

What is waiting for you. Covered in Inbox and approvals.

• Waiting on you: approvals you may decide, each with Reject and Approve. An approval for money asks you to confirm with a second button that names the amount, such as Approve $250.00.
• Waiting on others (folded): approvals you can see that someone else decides. An admin sees every pending approval; everyone else sees only their own.
• Items: everything else addressed to you: mentions, tasks, escalations, questions from agents, reviews, delegations, and updates such as "Pat Kim added you to 'Tour test' as observer". Under each item is who it is from and what kind it is, for example "OrchKernel · update" for the system's own updates.
• Two tabs: Unread (the default) and Everything.

When nothing is unread, Items reads "Nothing here."

The unread count#

The number next to Inbox in the sidebar is how many of your inbox items are still unread. It counts every unread item, approvals waiting on you included. When it is zero, no number shows. On a phone the same number sits next to the inbox button in the top bar, and the menu button carries an orange dot.

An item becomes read when:

• you press the small dot on its right (Mark read);
• you tap an item that has nowhere to go (a removal from a thread, for example);
• you decide the approval it is about, or answer the question it asks.

Opening an item that links somewhere (a thread, a task) does not mark it read. You have to press its dot as well.

To see it in the demo:

1. Sign in as Pat. On Threads, choose New thread, type any goal (for example Tour test), leave Template at None (free-form) and choose Create. The new thread opens.
2. In the thread's details panel on the right, choose Add people. (In a narrow window, press Details first.) Tick Maya Patel, set Role to Observer and choose Add.
3. Sign in as Maya. The sidebar shows Inbox with a 1, and the Inbox lists "Pat Kim added you to 'Tour test' as observer".
4. Open the item. The thread opens. Go back to the Inbox: the count is still 1.
5. Press the dot on the item's right. The item is marked read on the server, but the item and the count stay on screen until you reload the page. Reload: the count goes away and Items reads "Nothing here."

To see an approval in the count: as Maya, ask the Churn-risk watcher "Northwind wants a refund for the double charge" (see Quickstart). Ada's Inbox count goes to 1 and the refund is under Waiting on you, not under Items. When Ada chooses Approve, then Approve $250.00, the count goes away.

Threads#

Where people and agents work together. Covered in Threads and Asking an agent and following the work.

• Talk to an agent lists the agents you work with, grouped by team. Clicking one opens a private conversation with that agent.
• Your threads lists the threads you take part in. In a fresh demo it reads "No threads yet. Ask an agent something or create a thread."
• New thread starts one.

What you see under Talk to an agent depends on who you are. Maya sees her team's five agents under Support · your team: Churn-risk watcher, Knowledge-base writer, QA reviewer, Support Agent and Triage. Ada sees every agent in the company, grouped by team, including the system's own (Architect, Context capture, Curator, Designer, Distiller, Schema Steward) under No team. When an admin pauses a module, its agents stay in the list, greyed out with "paused" next to their names.

Work#

Tasks and runs. A run is one go of an agent at a task, step by step. Covered in Asking an agent and following the work.

• The Open tasks tab (its label also shows counts, such as "Open tasks (0) · 0 done") has the filters Open, Mine and All, and New task to create a task with a Title and Assign to a person or an agent. Each task has Details. A task assigned to an agent has Run now. A task assigned to a person has Mark done for its owner and its assignee. Its owner, or an admin, can Reassign it.
• The Runs tab lists every run you may see, with its state, agent, task, steps, cost, tokens and start time. Click one to open its trace in a panel.

In a fresh demo both lists are empty ("No tasks match.") until someone asks an agent something or creates a task. For example, Maya choosing New task, titling it Triage the new tickets, assigning it to Triage and pressing Run now gives a finished run under Runs (the demo's stub planner handles it without a model).

Curation#

Items the context module captured and left for a person to file: choose a function for each, or ignore it. (The context module captures what the company already writes down, such as meetings, email and chat; see Context capture.) Personal items reach only their owner; shared items reach the lead of the team they came from. Admins also see Forgotten people when there are any: shared items written by, or involving, a person who asked to be forgotten, to purge or keep. In a fresh demo the page reads "Nothing waits for you."

Module pages#

Between Curation and the Company heading, the sidebar lists the pages that your company's modules bring. They are grouped under a heading per section (Sales, Support, Engineering, and so on), with the sections in alphabetical order. Each page is a dashboard or a list drawn from the module's collections. Pages are data, not code: a new module brings its pages with it, and an admin can hide or move a module's pages from that module's Pages tab (see Modules).

In the demo:

The differences come from who may read what. The Sales pages read the leads collection, which only the Sales team may read. Ada is an admin but not in Sales, so she does not see them. On the Brain page the Leads collection shows her "No access" and "You cannot read this collection. Reads are governed by team policy." To give someone a page, give them read access to its data (see The brain).

When an admin pauses a module, its pages leave the sidebar. A page you may not see, or one whose module is paused, says "This page is paused or no longer exists." with a Go home button, rather than an error. Ada sees this if she opens Alice's Leads page address (/v/crm.leads).

Some module pages show a single record (for example a lead, opened from Alice's Leads list or from search). Those have no sidebar entry of their own.

The Company section#

Brain#

Every collection in the company: leads, tickets, roadmap items and so on. Pick one on the left to see its records as a table built from its schema, filter them, and open a record to see where it came from, its history, and roll it back. Collections you may not read show a lock instead of a count. Covered in The brain: collections, records and pages.

Knowledge#

What the company knows, as you may see it, with tabs All, Frameworks, SOPs, Enablement, Decisions, Glossary, Facts and Agent memory, and a filter by function. Entries waiting for a decision come first, with Accept and Reject for those you may decide. SOPs also lists each agent's playbook (Agents' playbooks), and Decisions the decisions logged in threads. Covered in Knowledge and decisions.

Directory#

Everyone in the company, in three tables: Agents, Humans and Teams (35, 9 and 5 in the demo). Each row shows role, team, trust, skills, open tasks, track record and status.

• Who can do finds the people and agents that have the skills you type, comma separated, and ranks them. Type the skill's id exactly as the Skills column shows it: ticket-triage and Find gives "1 candidate(s)", Triage. A word that is not a skill id, such as refunds (the box's own example), finds "0 candidate(s)".
• Click a row for its details. For an agent this includes Acts under (the people it may act for, and the limits), Has delegated, Ask agent for an agent you work with, and Let agent act for me. Open agent page shows the agent's Overview, Playbook, History and Scorecard tabs.
• Pick from library (every person) browses the agents the company can have.
• Hire an agent and Register an outside agent appear for admins only.

Covered in Agents, Delegations and, for outside agents, Outside agents.

Governance#

The controls, in tabs:

People (admins)#

Every person and their sign-in tokens: Issue token (the token is shown once, so send it privately), Revoke one token, or Revoke all of a person's tokens, which signs them out everywhere. Covered in Setting up a company.

Modules (admins)#

What the company can enable and what it has, in tabs Catalog, Installed, Connections and Agents, plus Describe a module and Upload a module. Open on a module shows its own page with tabs Overview, Teams, Agents, Connections, Automation, Pages and History (the Context module adds Sources), and Pause or Resume. Covered in Modules and Connections and integrations.

Events#

The append-only event log: every policy decision, write, approval and run step, newest first, one line each. Click a line for its full detail. Filter with Type. You see only the events you may see. In a fresh demo Ada's list is full of the demo's setup ("Actor added", "Skill added", "Tool added"), while Eli, an engineer, sees only the events his own actions produce: after he opens Knowledge, his list shows "Eli Novak: knowledge.recall allowed". Covered in Events and the audit log.

Setup (admins)#

Set up your company, in three parts: Company (the currency every amount is shown in, with Save currency), Blueprints you can install in one click, and Or describe it, where Ask the Architect drafts a blueprint from your description for you to approve. In the demo the SaaS startup blueprint shows "Already set up". Covered in Setting up a company.

The search box#

The Search box at the top of the sidebar searches the records and the knowledge you may read, as you type. It starts from two characters.

1. As Maya, type refund in the box. A list opens with "Refund for a double charge on the September invoice", marked Tickets, and the note "Matched on your words only: search by meaning is not set up here."
2. Click the hit. Tickets have no page of their own, so the record opens in a panel over the current page, with its fields, who wrote it, and Open tickets in the brain.

What to expect:

• A hit opens where it lives: a record in its module's page when it has one (Alice searching Litware opens the Litware lead's page), otherwise in the panel above; a knowledge entry on the Knowledge page.
• Enter opens the first hit when that hit has a page (Alice's Litware). For a hit that opens in the panel, such as Maya's ticket, Enter opens the panel and closes it again at once; click the hit instead.
• It looks in record titles and longer text fields of the collections set as searchable, and in knowledge. It does not search ids or email addresses: T-1042 and Northwind find nothing, although ticket T-1042 is from ops@northwind.example.
• Without an embedding model (the demo has none) it matches your words only, which is what the note under the hits says.
• "Nothing you may read matches." means exactly that: there may be matches you may not read.
• Escape, or a click outside the list, closes it.

Your profile and signing out#

Your name at the bottom of the sidebar opens Profile. It shows:

• Your Role, Team, whether you are an Admin, and your Sign-in id.
• Sessions & tokens: the tokens you sign in with, with New token (for another browser or a script; valid for 1, 7, 30 or 90 days, shown once), Revoke on each, and Sign out everywhere.
• Personal context: sources that may capture your own mail, chats or documents for you alone, with Opt in and Opt out. In the demo no source allows it ("No source allows personal opt-in."). See Context capture.

Under your name the sidebar shows your role ("Support lead" for Maya). An admin whose role is not called admin shows "· Admin" after it.

There are two ways out:

On a phone#

Below 1000 pixels wide the sidebar becomes a drawer.

1. Sign in as Maya on a phone (or in a narrow window). A top bar shows the menu button, the name of the page you are on ("Threads"), and the inbox button with your unread count. With unread items, the menu button has an orange dot.
2. Tap the menu button. The sidebar slides in over the page, with Close at its top, then the search box, every item, and your name and Sign out at the bottom.
3. Tap an item, for example Events. The drawer closes and the top bar reads "Events".

The drawer also closes with Close, by tapping the dimmed page beside it, or with Escape. Pages fit the width without scrolling sideways. In a thread, the participants and other details move behind a Details button (see Threads).

Developer mode#

Developer mode shows two extra things on a thread page:

• Explicit plan in the thread's message box, where you paste the exact steps an agent should run instead of letting a model plan them (useful in the demo, which has no model);
• the thread's raw data (thread object) at the bottom of the page.

To turn it on, open a thread and add ?dev=1 to its address, for example http://127.0.0.1:8080/threads/<thread id>?dev=1. Only a thread page reads the setting: adding ?dev=1 to another address, such as /threads or /work, does nothing. Once on, it is remembered in this browser, so later threads show it without the ?dev=1. To turn it off, open a thread with ?dev=0 at the end of its address.

A server started with --dev-auth also shows Explicit plan to anyone who signed in through its development sign-in.

Not possible yet#

• Choosing which sidebar items you see, or reordering them, as a person. An admin moves or hides a module's pages for everyone from the module's Pages tab.
• A light or dark theme switch in the workspace. It follows your system setting.
• Marking every inbox item read at once.
• Searching by meaning in the demo, or by a record's id or email address.
• Finding people and agents by a plain word in Who can do; it needs the exact skill id.

For developers#

The sidebar is built from two API calls, both under /api with Authorization: Bearer <token>:

Other calls behind this page: GET /inbox (unread items; ?all=true for everything), POST /inbox/:id/read, GET /search?q=<text>&limit=12 (returns hits and keyword_only), GET /directory/find?skills=<ids>, GET /tokens, DELETE /tokens/<your id> (sign out everywhere). See CLI and API reference.

The workspace refreshes /me and the inbox list when new events reach the browser. POST /inbox/:id/read writes no event, which is why a pressed dot does not clear the count until the next reload or the next event.

Developer mode is stored in the browser's local storage as ok.dev; the signed-in session as ok.session. Sign out clears ok.session only.