Actually you don't need to read our docs, just ask Clark questions

Ask from a terminal:

clarkcant ask "how do I connect Cursor to you?"

The CLI runs from a ClarkCant checkout for now, so without an alias the same question is:

# From a ClarkCant checkout (the CLI is not published to npm yet)
node apps/cli/src/main.ts ask "how do I connect Cursor to you?"

Or, from any AI tool that speaks MCP (Claude Desktop, Cursor, …), call the ask_clark tool:

{ "jsonrpc": "2.0", "id": 1, "method": "tools/call",
  "params": { "name": "ask_clark", "arguments": { "text": "how do I connect Cursor to you?" } } }

The rest of these pages are for when you want the exact routes, frames and flags.

Built on open standards

ClarkCant is one conversation with one Clark. The same Clark is reachable through ordinary, open interfaces, so any third-party app, script or AI tool can drive it without a custom SDK:

One token, one gateway, the same semantics everywhere. Every surface is served by the same runtime node, on the same origin, with the same bearer token. There is no second business-logic stack: an MCP tool, a WebSocket request and a CLI command all end up at the same HTTP gateway handler, so they behave exactly like the REST call underneath.

Approvals are deliberately not exposed to MCP. Deciding an approval is a human surface. An AI client must not be able to approve its own guarded action, so there is no MCP tool for it.

Slash commands

Type / in the composer to see the commands, listed ahead of your skills. With nothing typed, commands and skills share the list (half each when both have plenty), so your skills are always there too; type a few letters to reach the rest. Each one is answered by Clark in the conversation, as a message with a small card you act on right there, so nothing opens a screen of its own, except /settings, which opens the same Settings dialog the gear opens.

When a press on a command card does not reach your node, or gets no answer in time, the card says so and offers Try again beside it, which sends the same press again; this works for /thinking, /login, /logout, /develop and forgetting a chosen folder. A press your node refused says why and offers nothing to repeat, because sending it again would get the same answer.

A skill whose name is also a command's is listed and written as /skill:<name>, so choosing it uses the skill; typing /new yourself still runs the command.

A command typed in the middle of a sentence is just text. Commands are not sent to the model. See provider sign-in routes.

Report a bug or request a feature

Type /report to get a card where you choose Bug or Feature, say what happened or what you want in your own words, and open “What will be shared” to see exactly what goes with it. /report bug … and /report feature … (also lỗi and tính năng), a sentence to Clark, or your voice go one step further: Clark prepares the report and shows the issue exactly as it would be filed. None of these sends anything. Only your own press on Create issue files the report; Clark, its tools and voice cannot. Reports go to digitopvn/clarkcant and nowhere else.

Your execution policy applies to that press. If it denies the action, the report is refused and nothing is sent; if it would ask first, your press is the answer. Before filing, Clark looks through open issues and issues closed in the last 90 days, and when an open issue clearly matches, your report is added to it as a comment instead of opening another.

The result card says which way it went: Issue opened or Added to an existing issue (only once Clark has read the report back from GitHub), Outcome not known yet, Not filed, GitHub access needed or Refused by your policy. When GitHub's answer never arrived, Check again only looks; it never sends. Send again appears only once GitHub shows the report missing at least two minutes after the attempt. If Clark cannot tell whether GitHub kept it, the card says so, links the issues you opened since then and a prefilled new-issue page, and offers Send anyway, which may file it twice. Clark never sends a report again on its own: after a restart, reports left unsettled are checked, not resent, and the result is posted in their conversation.

If your press on Create issue does not reach your node, the card offers Try again, which sends the same report the same way. If it was sent and anything other than a refusal your node decided came back (the connection dropped, it timed out, a relay in between failed, or your node hit an error of its own), your node may have filed it, so the card never says it was not filed: it says the outcome is not known yet and offers Check again, which only asks your node where the report stands, with Try again beside it when sending the press again can get through. A press that arrives while your node is still sending the report is told so, in your language. Your node takes a report for one send before it asks GitHub anything, so a report it already sent, or is sending, is checked rather than sent again, even when two presses overlap; a retry never files a report twice. A Check again that does not go through leaves the outcome not known. If your node answers but this version of the app cannot read the answer, the card says the report may or may not have been filed, never that it failed, and offers Check again. A refusal your node decided offers nothing to repeat and does not suggest trying again. After Try again or Check again, keyboard focus stays on the card's status.

Filing uses the GitHub token (github_token) you stored for signal sources. Without one, the card shows GitHub access needed with a link to GitHub's new-issue page, already filled in, so you can file it yourself. The repository also has Bug report and Feature request issue templates for filing by hand.

What is shared, and what never is. Your words, with secrets redacted, and safe diagnostics unless you turn them off: the ClarkCant version, OS and architecture, runtime, locale and input mode, the part of ClarkCant it is about, the provider and model, and an error as a short redacted excerpt with a fingerprint. Never sent: the conversation, system prompts, files, environment variables, raw logs or credentials. Your home folder is written as ~, and @mentions in your words are neutralised so a report notifies nobody.

Asking Clark to work on an issue you filed is not available yet; the result card says why. See the report routes.

Signing in to AI providers

Open Settings → AI & Routing to sign in to the AI providers pi can answer with, under the provider and model picker. Each provider shows only the ways in pi offers for it: an account sign-in when the provider has one, an API key when it takes one. The sign-in runs inside the row: open the provider's page and paste the code it shows, or type a key into a password field. What you type goes straight to pi and is never shown again. Typing /login or /logout in the conversation does the same.

A signed-in provider says where its credential comes from: stored by pi, the node's environment (.env or the shell), handed over when the node started, pi's models.json, or a key pi finds on its own. Only a credential pi stored can be signed out or replaced here. For the others the row says so and where to remove the key. After a sign-in or sign-out the provider list and the model list refresh, so a newly available model can be chosen right away.

Inbox and notifications

Open the inbox from its header badge, with the keyboard, or by asking Clark in text or voice: “open the inbox”. It brings together command approvals, package permissions, approvals a running task raised, open questions and stored notices about background work, expired requests and available updates. Clark's control_app tool reaches the same inbox.

Granting an approval raised by a running task lets the node run it again; if the node cannot accept the run, Clark says nothing has run and you can ask again. Denial or expiry ends the task. That decision belongs to you; machine interfaces refuse it. See task approval decisions.

Settings → Control offers desktop OS notifications and browser Web Notifications, with per-group toggles and quiet hours. The browser must grant notification permission. Notifications appear only while the app is hidden, unfocused or in orb/compact mode, and their redacted text never includes command lines. Clicking one opens the inbox on its item; an item already dealt with is reported as such.

If the OS refuses or fails to show a notification, an inline status beside the OS notification toggle explains why and says the item remains in the inbox. It clears after a notification is shown again. Update checks offer only versions the installer accepts on your host and stay silent while the node is offline.

Where packages come from

When you ask Clark to find a package, the results card lists packages from your own index file, from any catalog your operator added, and from the official ClarkCant Marketplace, which is on by default. Each row names its source, and a source that did not answer is named rather than shown as an empty list. The official Marketplace may list few packages or none yet. A package keeps the source it was installed from: its updates come only from there, and the update notice names that source. Configuration, precedence and the error codes are in where package listings come from; hosting your own catalog is in the directory feed.

The desktop window

The desktop app reopens the conversation window where you left it: same position and size, maximized or full screen if it was. If that display is no longer attached, or the window would open out of reach, it opens at the default place and size instead. A window remembered from a larger screen is shrunk to fit.

Window controls on Linux: X11, Wayland and Hyprland

The compact bar, the orb, expanded, full screen and the pin behave the same on macOS, Windows and Linux under X11, including a Wayland session where the app runs through XWayland (started with --ozone-platform=x11): the app sets the window's size and position and can keep it above other windows. Under XWayland your compositor may still override placement or stacking.

Under native Wayland, which the desktop app uses by default in a Wayland session, the compositor decides where windows go, and no standard protocol lets an app keep its window above others. So there the app only asks for a size, which a tiling compositor may also ignore for a tiled window, and it never pretends otherwise: the pin button is not shown, a pin request is refused with the reason instead of being sent, and every change of window mode reports position as unsupported.

On Hyprland, for example Omarchy, you can opt in to a Hyprland backend that drives the window through Hyprland's own commands: compact and orb float the window at their size, the orb is also pinned to every workspace, expanded maximizes it, and pin floats and pins it. Minimize is refused, because Hyprland has no minimized state. Turn it on by starting the desktop app with --window-backend hyprland or with the environment variable CLARKCANT_WINDOW_BACKEND=hyprland. It takes effect only when Hyprland is actually running; anywhere else the app keeps its default behaviour. If talking to Hyprland fails once, the window goes back to the native Wayland behaviour above for the rest of the session.

Not yet verified on a real Hyprland. The Hyprland backend is off by default because it has only been tested against a stand-in, not on a real Hyprland or Omarchy desktop, and no Omarchy package ships yet. Of the Linux sessions, only X11 has automated coverage. The steps to check it on your own machine are in the platform smoke guide.

Version and what's new

Ask Clark “what's new?” or “what version is this?”, type /changelog (or /changelog 1.4 for what came after 1.4), or open Settings → Experience → Version & what's new. Each shows the same card, drawn by your node: the installed version and channel, and the release notes that came with this build, grouped as breaking changes, features, fixes and other changes. The notes are embedded in the build, so the card works offline. Clark may sum the entries up in your language, but it cannot add one: the card is your node's, and the entries are the ones the release recorded. The card has no Update button, update status or channel choice, because there is no update service yet. See GET /changelog.

Run from source. A checkout carries the release notes that were committed with it, and those stop at a recorded commit. For a source install, the card, /changelog and Clark name that commit and its date, and say the checkout may include later changes that are not listed. A git pull does not add them. Until the first release is published, the card's link reads “Full change history” and opens the commit history up to that commit.

To update a source install, follow Updating in the installation guide: git pull, then node tools/setup.mjs. If you edited a file that the update changes, git pull stops with an error instead of replacing your edit; keep or undo your change, then pull again. This is the only update path today: Clark has no self-updater.

Versions and channels

The version comes from the commits since the last release, written as Conventional Commits, and follows semantic versioning: a breaking change is a major release, feat a minor one, and fix or perf a patch. main is the stable channel (1.4.0); dev is the beta channel (1.5.0-beta.1, …), and a beta never reaches the stable channel. The full rules, and how to run the release plan from a checkout, are in releases; run corepack pnpm install at the repository root before the release tooling's own install, because the planner reads the app's shared contracts.

Not available yet. No release is published. Installers, signed builds, published release notes and updating from inside Clark come later.

Labels in your interface language

Task cards name their status and evidence in the interface language, for example “needs your decision” or “outcome unknown”; a status this version does not know is shown as sent. In the widget library, each widget's source (Built-in, Installed package, Local development package) and status (Stable, Experimental) are worded the same way. Settings → Extensions lists each tool by what it does, with its name beside it, under “On this node” and “The agent's own (pi)”; the instructions the model is given for a tool are behind “What the model is told”.

Text your node writes into the conversation itself follows the interface language you choose in Settings (Tiếng Việt or English, the preference experience.language; Vietnamese when none is set). It is written in that language when it is written, not translated by the app afterwards, so lines already in a conversation keep the language they were written in. This covers Clark's reply cards and their notes (which model is answering, no model, a model failure, a stopped reply, turn metrics, a refused block), the start-screen samples and the labels of surfaces Clark composes, reports on background work and tasks (started, done, stopped, failed, queue full, retries, deadlines), stop and approval receipts, recovery after a restart, automation messages, the labels of rows for tools your node defines, question rows and their expiry, and the status of work handed to a paired node and the files it brought back. It also covers the model note and the other cards your node writes; the rows and receipts an approved command or package call leaves, including the notes on what a command printed (“No output.”, the truncation marker); approval cards for installing a package, granting it a permission and loading map tiles, and the reason a task is waiting for an approval; how a task ended, when your node wrote that itself (a refusal before the task ran, a run with nothing to show, a stop, and an answer you recorded for an action whose outcome was unknown); the notice that an automation run could not start; inbox notices, including the word used for a notice with no title; the start-screen suggestions; the tool labels under Tools in Settings → Extensions; and the answer when you decline a spoken or typed command, or when its confirmation has expired or was already used.

Kept as written. Text already written keeps its language when you switch: an approval card asked before the switch keeps its wording, and so does the notice of its expiry where it quotes that card. Suggestion chips already on screen stay as they are until the next fetch. Labels and summaries written by a package or extension are shown in their author's words. Text sent to a paired node stays as it is, because your node does not know the language of that node's owner. Text your node did not write, such as an error message or what a run reported, is quoted as written rather than worded into the sentence. The message stored for a task, and what a paired node is sent about it, keep their original wording. What the model is told is not translated: it is the model's input, not text you read.

Coding terms when you speak

When you speak a sentence that mixes Vietnamese and English coding terms, your node fixes how the terms were heard before the sentence is read as a message, a command or an answer: “sửa lỗi stale closer trong use effect” becomes “sửa lỗi stale closure trong useEffect”, and “cài core pack rồi bật p and pm” becomes “cài Corepack rồi bật pnpm”. The fixed sentence replaces the line being written, so each thing you say is one line, not two.

The fixes are fixed rules, not a model: casing, spacing, known mis-hearings, and a one-letter slip in a tool, provider or model name. Each needs evidence in the sentence, and the terms come from what your session knows: your projects, the active branch, the symbols, paths and issues the conversation mentioned, skills, extensions, the current model and a built-in coding glossary. A one-letter fix never reaches a symbol, path, branch or package name, or a word with a digit in it, because its neighbours are other real names or another version. A real word or a person's name is never treated as a mis-hearing, part of a longer written word is never touched, a span that could be two terms is left as heard, and a sentence already written correctly comes back unchanged. No model rewrites what you said.

A dedicated recognizer, if the operator turns it on

By default your words come from the live voice session's own transcription. An operator can have one node use a dedicated recognizer instead by starting it with CC_VOICE_RECOGNIZER=gemini-transcribe. It uses the same Gemini credential as the live session, which stays the voice and still hears you interrupt. While you speak, its first reading is shown and replaced, and only the settled sentence is sent, once. A sentence cut by the provider's session limit stays one sentence. If the recognizer cannot open in time or fails partway, the live transcription takes over, starting from what the recognizer had not delivered. With it on, an unclear technical part of one sentence may be heard again from that sentence's own audio, and a fixed rule picks between the readings. There is no setting for this in the app. An unknown value is ignored and the node says so on stderr.

What the recognizer is sent. Besides your voice, which the live session hears anyway, the dedicated recognizer is sent your session's terms as Gemini's customVocabulary: names such as identifiers, file paths, branch names and issue numbers from the conversation. Every term passes the same secret redaction, and a term redaction would change is left out. The conversation's sentences are used only to rank the terms; they are never sent. Without the setting, the terms stay on your node and are only used to fix the transcript. See the system architecture and ADR-003.

Terminal in the conversation

Ask Clark in text or voice to “open a terminal in the project folder” to open a real shell in the conversation. Full-screen programs such as vim and htop work there. A command Clark proposes follows your execution policy; when it needs your approval it is prefilled and runs only when you press Enter. Clark does not type over a line you are editing. Press F6 to move focus out of the terminal.

Send the selection, the last finished command's result or the screen back to the conversation; the button says which will be sent, and credential-like strings are redacted before the model sees them. A terminal has one driver at a time: other cards observe it and offer “Drive here”. Its Progress panel lists other terminals, command invocations and background work. The card reports connecting, disconnected with reconnect, ended with an exit code, gone from the node or unavailable because the node has no PTY.

Settings → Widgets → Browse lists Terminal under System cards with a description, a static illustration labelled as an illustration and a hint to ask Clark. It has no live preview or open button. Search works with or without Vietnamese tone marks; choosing a family other than All hides System cards. The /terminal socket belongs to this app card.

Long conversations

A long conversation stays one conversation. It opens on its newest messages, and older history loads as you scroll up, with no button to press; it is put in above without moving the line you are reading. When you are more than a screen above the bottom and something new arrives, a Jump to latest button appears over the foot of the conversation, and it goes away once you are at the bottom. If older history cannot be read, the conversation says so where it would have appeared, keeps everything on screen, and offers Try again.

To stay fast, only the messages around the screen are kept in the page; the one you are focused on, a playing player, the embedded video or map you last used, a selection and the newest message always stay. A card you scroll away from and back to keeps how you left it, such as an open fold, a draft or a search, but never a secret typed into a credential card. Because of this, the browser's find-in-page sees every message only in a conversation of up to 60 messages; in a longer one it finds only the messages near the screen. Searching further back is not available yet. See reading a long conversation.

Charts and tables in answers

When an answer has structure, such as numbers to compare, a trend or a list of options, Clark shows it as a chart or a table in the same reply without being asked. Asking “compare the benchmarks of model A and B” is enough; you do not have to add “as a chart”. Clark draws the numbers it actually gathered, says where they came from, and never invents values to fill a chart.

Numbers Clark gathered for an answer are kept on your node as saved data you own, and the chart labels them as saved data rather than live. A bar chart can put several series side by side, with a legend, so two models can be compared on each benchmark. Rows that do not fit, such as too many rows or a cell that is too long, are refused whole with the reason; nothing is shown half-drawn. Today these rows draw in a chart or table shown on its own, not inside a composed overview. See the widget developer standard (§8.6.1).

Kanban boards in the conversation

When a reply has a board, move a card with a mouse, touch or keyboard. The built-in board is a view of work Clark already knows; it does not connect to a project service by itself. If a board is bound to change data elsewhere, that request goes through Clark's normal action and policy path. See the widget developer standard (§8.10).

Tree view

When Clark already has hierarchical information, it can appear as a nested outline using canvas.tree@1. Each item has a stable id and label, with optional secondary text, a closed-set icon and children. This is a view of known information, not a file browser: the tree reads no service and changing selection or expanding a branch does not edit source data. Its selection and expanded branches are saved with the widget and restored with its pin; saved ids absent from a later tree are ignored.

Arrow keys move through visible items and open or close branches; Home and End move to either end, type-ahead finds a label, and Enter or Space selects an item. Screen readers receive each item's level, position, set size, selected state and expanded state. The node validates a bounded hierarchy before it is shown. See the tree contract and bounds and the internal widget development guide.

Diagrams and graphs

When Clark has a flow, a dependency graph or a small tree to show, it can draw it with canvas.diagram@1. Your app draws the SVG itself and nothing in it runs: labels are text, shapes and lines are numbers from a shared layout, and there is no HTML, foreignObject, link, image, style or handler a label could name.

A diagram holds at most 60 nodes and 120 edges. A node id is at most 64 ASCII letters, digits, _ and -. A label is one line of at most 80 characters, an edge label at most 40, a group name at most 40 and the title at most 200. A node's shape is box, round, diamond or circle. An edge's direction is forward, both or none, and it can carry a label. Groups are one level deep. The node refuses a repeated node id, an edge to a node that is not there, an edge from a node to itself, the same edge twice, too many nodes or edges, an unknown field and a hidden character, and each refusal says why in the host's own sentence.

layout is layered (the default) or tree, and direction is TB (top to bottom) or LR (left to right). The layered layout breaks cycles, layers nodes by longest path and bends long edges through the layers they cross. The tree layout centres children under their parent and refuses a graph that is not a forest. A gap that holds an edge label is widened to fit it, and edges joining the same two nodes are drawn apart. The layout is deterministic: the same props give the same drawing on the node and in every client, and the largest accepted graph is laid out in bounded time.

Mermaid flowcharts

Clark can also hand show_view a Mermaid flowchart: { "mermaid": "flowchart LR ...", "title"?, "layout"? }. The node reads a documented subset of the flowchart syntax itself and keeps only the resulting diagram model. It never stores the Mermaid source and never loads Mermaid's renderer. The subset is:

A source naming more than 60 nodes or 120 links is refused as soon as it passes the limit. Everything that configures or extends Mermaid's renderer is refused by line, with the reason: click, href, call, style, classDef, class, :::, linkStyle, %%{init}%% directives, front matter, HTML or entity codes in labels, Markdown strings, fa: icons, other node shapes, other link styles, & chains, nested subgraphs and other diagram types.

Selection and keyboard

Choosing a node sends diagram.select with { selectedId }. The node checks it against the current diagram and keeps it as widget state, so the selection survives a reload; a restored id the diagram no longer has is ignored.

Each node is a button, and one node is in the tab order. The key along the flow (Down for TB, Right for LR) follows an edge forward and the opposite key follows one back. The cross keys step within a layer, and Home and End go to the first and last node. Enter or Space selects the focused node, or clears it if it is already selected, and Escape clears the selection. A node's accessible name gives its label, shape and group, and the nodes it leads to, comes from and is linked with, each with the label of the edge between them (“leads to Ship (yes)”). The selected node marks its edges and neighbours with stroke width and dashes as well as colour, and a live region announces the change. A wide drawing keeps its size and scrolls inside its card, so the page never scrolls sideways. The diagram has no motion of its own and follows both themes.

The semantic document gives the node and edge counts, the layout and direction, and the selected node with its neighbours and their edge labels. A text alternative, also shown under the drawing, lists every node with its outgoing edges. See the Mermaid subset parser and the widget developer standard (§8.12).

Current limits. When two labelled edges leave the same node into the same gap, their labels can sit close together; labels always stay clear of nodes. Like the tree, a diagram cannot yet be placed as one part of a view Clark lays out.

Maps

When Clark has places to show, it can draw them on a map with canvas.map@1: points with labels, lines such as routes, and areas. The map is drawn over an offline basemap that ships with the app, so with the default settings a map makes no request beyond your node and nobody learns which part of the world you are looking at.

The basemap is Natural Earth 1:110m land, version 5.1.2, which is in the public domain. It is generated by a build script that pins the source file's SHA-256, and the map credits Natural Earth under every drawing.

What a map holds

Positions are WGS84 [longitude, latitude] in a strict subset of GeoJSON geometry: Point, LineString and Polygon, an outline with up to 15 holes, each ring closed. A map holds at most 200 features and 5,000 positions in total. An id is at most 120 characters, a label 120, a description 300 and the title 200. The map fits its features, or an optional view of { center, zoom }, with a whole zoom from 0 to 18, replaces the fitted view. Geocoding, routing, your device's location, vector tiles, 3D, clustering and editing are not part of this widget, and the map never asks for your location.

The node refuses a map before it is shown, and says why: coordinates outside the globe, an unknown geometry type, too many features or positions, over-long or repeated text, hidden characters, and any URL. A key that names a link (url, href, src, tile, endpoint and the like) or a value that is one (https://, //, data:, javascript:, blob:) is refused, so a map's props can never name a host. Places Clark puts on a map are Clark's statement, and the map carries no “live” badge.

Map tiles, only if you choose a provider

Map tiles. Maps draw an offline basemap and work fully without tiles, which are off by default. To add provider tiles, open Settings → Extensions → Map tiles and enter the provider's origin, tile path, attribution and maximum zoom. This sets your node's tile policy, the preference maps.tilePolicy, which names one provider. If the provider needs a key, enter it with the header or query parameter it goes in. The key is bound to the origin you entered it for: ClarkCant sends it only to that origin and never shows it again. You can also ask Clark to turn tiles on or off. Clark follows your execution policy: in Autonomous mode the change happens at once and can be undone in Settings; in Ask every time mode you approve it on a card. In Guarded mode, naming a provider asks on a card and turning tiles off happens at once, and Deny everything refuses both. Clark can never move your key. If Clark sets a provider that needs a key at a different origin, the map stays offline until you enter the key again for that provider. GET /map-tiles reports why maps are offline in its offline field: no-provider, key-unavailable (no usable key saved) or key-origin-mismatch (the saved key belongs to another origin).

AI clients over MCP, the WebSocket relay and clarkcant api cannot write the policy or the key directly: those routes answer 403 PERSON_ONLY, and a client that wants tiles changed asks Clark. The routes are listed in the node's API.

Selection, keyboard and the table

Choosing a feature sends map.select with { selectedId }, empty to clear it, and moving the map sends map.view with { center, zoom }. The node checks both against the current map and keeps them as widget state, so the selection and the view survive a reload. A pan is saved 400 ms after it settles, so a run of key presses is one write. In a view Clark lays out, map.select is also an event with a selectedId field that other parts can follow.

The map can be focused and used by keyboard:

Dragging with a pointer pans too. On a touch screen, a swipe over a map you have not tapped scrolls the conversation; once you tap the map, a drag pans it. The zoom-in, zoom-out and reset buttons are 44 px. A live region states the view once it settles, and the selection. A pan slides only when motion is allowed; with reduced motion the view moves at once. The map follows both themes, and a narrow map moves its controls under the picture and draws its labels larger, without overflowing at 390 px.

Below the map, a table lists every feature with its kind and position. Its Select button selects the feature on the map and brings it into view, and selecting on the map highlights its row. That table is also the map's text alternative.

The semantic document gives the feature count and the count of each kind, the visible bounds and zoom, the selected feature's label and coordinates, and whether tiles are offline or from the policy's origin. See the map contract and bounds and the widget developer standard (§8.13).

Current limits. The map is one world that does not repeat: the view stops at the antimeridian, and a map does not wrap across the 180° meridian. The basemap, features and tiles are each drawn once, so they always agree.

Audio player and document preview

Clark can play a sound with canvas.audio@1 and show the text of a PDF or text file with canvas.document@1. The page never fetches anything for either widget. Clark names a source, and your node reads it, checks it under its media content policy and stores only what it checked.

Where the sound comes from

Clark names exactly one source, a title and, if it has one, a transcript of at most 4,000 characters:

Your node fills in the reference the page plays, the type, the length and the size, and for a fetched file the origin it came from. Clark cannot supply any of these, so a player never claims a type or a length nobody checked. The page only ever sees a reference to a file your node holds, never the outside URL. The same checks of type, size and length apply to an audio file you already hold.

Playing

The player uses the browser's own controls, keyboard included: focus it and press Space to play or pause. It never plays by itself, neither when it first appears nor when it comes back. It keeps whether it was playing, where it was and how long it is, written the same way as a video's, so after a reload it opens paused where you left it. A transcript, when there is one, is plain text in a section you can open with the keyboard, and a hidden character in it is drawn as a visible marker. Voice, the note added to your next turn and inspect_ui know the title, whether it is playing, its position and its length, and whether it has a transcript.

Previewing a document

Clark names a PDF or a text file in this conversation (plain text, Markdown, CSV, tab-separated values or JSON), by its artifact or attachment id. Your node reads its text, a PDF's through your node's own reader, and keeps at most 20,000 characters in at most 10 pages of at most 2,000 characters each, breaking at a line end or a space. A notice says when the preview was cut short and how much of it is shown. The preview is text only: pictures and layout are not shown, and nothing in the file is treated as markup or run. A hidden character is drawn as a marker, with a warning.

The page's text sits in a region a keyboard can reach. Tab moves to the Previous and Next buttons and Enter turns the page. At the first or last page the button stays focused and is announced as unavailable, a new page opens at its top, and the page number out of the total is announced politely. The page you are on is kept with the widget, so it is still open after a reload, and voice, the next-turn note and inspect_ui know it. A WAV is not a document, and the preview refuses it.

Both widgets follow both themes and fit at 390 px. With reduced motion they add no animation or transition. Neither can yet be placed as one part of a view Clark lays out: each is shown on its own, where your node checks its source. The Widget Library shows sample cards; the audio sample says it cannot be played rather than pretend.

The media content policy

Your node fetches audio from the web only from origins you list in CC_MEDIA_ORIGINS, a comma-separated list of bare https origins, at most 32. It is empty by default, so your node fetches nothing until you name an origin. A list with any entry that is not a bare https origin is ignored as a whole: your node allows nothing and says why once at startup. Each fetch follows these rules:

Every refusal ends with the rule it broke, as (media policy rule: <rule>), so Clark can tell you what to change. A file that passes counts against your storage. The page's own content policy is unchanged. See the rule names, the media content contract and the widget developer standard (§8.14 and §14.5).

Current limits. When a conversation loads, the page reads the whole file of every placed player, even though it plays nothing until you press play; reading it only when needed is tracked in #403. Each saved playback position is a full widget-state write, a cost tracked in #380.

Pictures and video in the conversation

A gallery or carousel keeps the picture you chose. The choice is stored with the widget, so it is still selected after a reload or a pin restore. A local video keeps whether it was playing, where it was and how long it is. When it comes back it opens paused at that position and never starts playing by itself.

Clark knows what you are looking at. Voice, the note added to your next turn and Clark's inspect_ui tool describe the selected picture (“showing picture 2 of 3”, with its alt text) or the video's playback state. While a video plays, its position is saved at most once every three seconds, and at once when you pause, seek or it ends. Saving when you leave the page is best-effort, so a “playing” state older than eight seconds is reported as paused at the last saved position. If your machine refuses a save, the widget says why beside it: a gallery or carousel shows the stored picture again, and a video stays where it is.

A view Clark lays out can include a gallery or carousel of your own imported pictures, newest first. Clark names only the widget and how it is wired; pictures it names are ignored. Choosing a picture sends media.select with { selectedIndex }, counted from 0, so another part of the view wired to the same value follows it and the view's state reports it.

The app's page and desktop window policy allow media-src 'self' blob:, only so a video can play from an object URL the app creates from bytes it fetched with your node's token. No remote media origin and no data: media are allowed.

Current limits. Your node cannot import video files yet, so a local video plays only from a reference your node already serves. A composed gallery or carousel keeps the pictures that were there when the view was laid out; pictures imported later appear only in a newly composed view. Each playback save is still a full widget action; reducing that cost is tracked in #380. See the widget developer standard (§8.11).

Quickstart

  1. Run a node. The installer sets one up; from a checkout it is node apps/runtime/src/main.ts. It listens on http://127.0.0.1:8765, loopback only by default.
  2. Find the token: localToken in <data-dir>/identity.json. The default data dir is ~/.clarkcant; in Docker the data dir is /data (token in /data/identity.json).
  3. Check the node and discover its surfaces. These three routes need no token:
export CLARKCANT_URL="http://127.0.0.1:8765"
export CLARKCANT_TOKEN="<token>"   # localToken from <data-dir>/identity.json
# Public: no token needed
curl -s "$CLARKCANT_URL/health"
curl -s "$CLARKCANT_URL/.well-known/clarkcant.json"
curl -s "$CLARKCANT_URL/openapi.json"

/health reports liveness, the runtime platform and the negotiated protocol, and no node identity. /.well-known/clarkcant.json lists every surface (api, mcp, websocket, cli) and its endpoints. /openapi.json describes the stable REST surface.

Then send Clark a first message:

# 1. Create a conversation → 201 { "conversationId": "…", "homeNodeId": "…" }
curl -s -X POST "$CLARKCANT_URL/conversations" \
  -H "Authorization: Bearer $CLARKCANT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "title": "From my app" }'

# 2. Talk to Clark in it
curl -s -X POST "$CLARKCANT_URL/conversations/<conversationId>/messages" \
  -H "Authorization: Bearer $CLARKCANT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "text": "What can you do on this machine?" }'

Authentication and errors

{ "code": "UNAUTHENTICATED", "message": "…" }

Keep the token private. It gives full access to your Clark. The node binds to loopback by default; --allow-public-bind exposes it and needs TLS in front. Sign-in with OAuth is not available: the bearer token is the only credential.

How Clark picks context

These environment variables on the node choose what context Clark sends the model with each message:

What goes to the Jev provider (only with CLARKCANT_CONTEXT_DECIDER=jev, and only when it is asked): the message being answered, redacted, at most 300 characters (400 for a tool-family choice), plus each candidate memory note or earlier message that is public or internal as a whole, redacted, at most 200 characters. Nothing else leaves the node, and Jev grants nothing.

Choosing the decision provider

Jev, from TypeSafe, answers your node's selector by default. The selector is separate from the conversation model: it only answers the small typed questions Clark asks while composing a reply. Instead of Jev you can choose Cloudflare Clef on Workers AI, or a decision model through OpenRouter's decisions API. Clark's policy (what is offered, what is redacted, the thresholds, the time budget and every fallback) is the same whichever provider answers, and every provider receives the same redacted request; only the endpoint, the credential and the pinned model differ. Changing provider changes who receives that request, so it is a data-sharing decision as well as a technical one. With OpenRouter two parties receive it: OpenRouter, and the company serving the model you pick.

Choosing it in Settings. Open Settings → AI & Routing → Decision provider, beside Provider sign-in and separate from the conversation model. The section shows the provider and model in effect, a badge saying what chose them (Settings, the environment, or the default), its status (ready, local only, misconfigured, no key, or off) with the reason and what to do about it, and the last call since the node started. Pick Follow environment, TypeSafe Jev, Cloudflare Clef or OpenRouter. Cloudflare adds its two models and an account-id field; OpenRouter adds a model-slug field, and nothing is saved until you enter a pinned slug (OpenRouter's own routers, such as openrouter/auto, are refused). Each provider has a key card that says where its key comes from (saved on its card, saved in Credentials for TypeSafe, the environment, or none). The Cloudflare and OpenRouter cards have Save and Remove; a key you type is cleared once saved and never shown again. The TypeSafe key has one place, the Credentials list on the same tab, so the TypeSafe card has no field of its own and its Go to Credentials button moves focus to that row's key field. Saving or removing the key there updates the card at once, without a reload. A reason the app does not know yet is shown as a generic message in your language. Your choice wins over the environment variables below, and Follow environment hands the choice back to them. A change applies from the next decision; the node does not restart. The same choice is available over the node's API, and only a person can make it: an AI client or another machine surface cannot choose which third party receives a decision.

Choosing it in the environment. An operator who configures the node without Settings uses these variables:

CLARKCANT_DECISION_PROVIDER=cloudflare
CLARKCANT_DECISION_MODEL=clef            # or clef-flash
CLOUDFLARE_ACCOUNT_ID=<account-id>       # 32 hexadecimal characters
CLOUDFLARE_API_TOKEN=<token>             # allowed to run Workers AI

# or
CLARKCANT_DECISION_PROVIDER=openrouter
CLARKCANT_DECISION_MODEL=cloudflare/clef-flash   # a pinned slug
OPENROUTER_API_KEY=<key>

Environment changes, including CLARKCANT_JEV_LOCAL_ONLY and CLARKCANT_JEV_ENABLED, still need a restart, and nothing in Settings can lift local-only.

When the provider is unavailable, your node falls back and says so. A missing credential, a malformed setting, CLARKCANT_JEV_LOCAL_ONLY=1 (which refuses every provider), a credential left in the request, a timeout, an error or an answer it cannot trust all end the same way: the call is reported unavailable with its reason, it is not retried, and the work goes on along the deterministic path. Composed surfaces compile without the selector, search ranks with BM25 and context keeps its ranked order. At startup the node prints one line about the selector, such as selector: clef-flash pinned on cloudflare, 4000 ms per turn or selector: disabled (no credential or local-only); composed surfaces use the deterministic path. Telemetry lines and stored decision records name the provider only when it is not TypeSafe. See the selector configuration.

Decision calls carry only public and internal content. Whichever provider answers, what a person, a file or a record supplied is limited to those two classes, and anything above them is removed before the request is built, never sent and filtered afterwards. A candidate that stands for your data (a search result, a memory note or an earlier message) is offered only when the whole record is within that limit; when fewer than two search results remain, the ranking stands and no provider is asked. Free text (your words, a directory name, a description, your own guardrail rules) is redacted, cut and checked again, and text still above internal is sent empty. When that empties the message or query the decision is about, no provider is asked and your node keeps its usual answer: its own ranking, every tool family, or no change to the turn. What your node writes itself is exempt, because a dated model id reads as a phone number: identifiers such as option ids, refs and counts, the node's fixed instructions, and catalogue descriptions such as a model route's alias (provider/modelId), a template label or a tool family's description. The credential check still covers them.

Size limits. A request over 64 KiB serialized is not sent. A provider's error body is never read: it is cancelled unread, and never returned, logged or stored. An answer over 256 KiB is not read past the limit and is treated as malformed, whichever provider or transport delivered it. Each case falls back as described above.

Switching back to TypeSafe. Choose TypeSafe (or "follow the environment") in Settings, or unset CLARKCANT_DECISION_PROVIDER (or set it to typesafe) and restart. A surface another provider chose still replays without asking any provider, and its record still names that provider and model. Rolling the node itself back to an older release is different: a release that does not know that provider cannot read a surface it chose, so replaying or refreshing it fails. Switch the provider back first, and keep a release that reads those surfaces for as long as they matter.

Checked live on 2026-10-08, with synthetic requests only. Cloudflare clef and clef-flash answered correctly both directly and through OpenRouter. On that day TypeSafe Jev did not answer in time, directly or through OpenRouter, so there is no fresh live result for it. OpenRouter marks its decisions API as alpha. Cloudflare's benchmarks of Clef against Jev are the vendor's numbers on the vendor's workload, which is why TypeSafe stays the default.

What a model may be sent

Every block your node adds to a model's context is labelled public, internal, confidential or secret, from its text alone and before anything is ranked or sent:

A model profile may say what it receives with trustClass (local, first-party, approved-third-party or untrusted) and allowedDataClasses. By trust class, local may receive everything, including secret; first-party and approved-third-party up to confidential; untrusted only public. With both set, the profile receives only what both permit. A list with no trust class is taken as written, so it can add secret to an unlabelled profile. A profile with neither receives everything but secret, and a model several profiles name receives only what all of them permit.

With CLARKCANT_CONTEXT_PLANNER on, a block above the answering model's ceiling is left out of the recap, the memory brief, the earlier messages, the context a background run or task worker retrieves (including its read_context reads), project instructions, and the results of search_history, each judged on the whole stored entry, not only the snippet shown. Each says how many blocks were withheld, never what they said, and the recap does not point at a tool to read them back. Jev is offered only public and internal candidates.

Background work leaves out a model profile that may not receive the work's class (the class of the request or the task goal), whether the planner is on or off. When no profile qualifies, or routing fails, the work falls back to the node's configured model only if that model may receive what the work sends, with the retrieved context narrowed to that model first. When the class is what left every profile out, the node writes one JSON line to stderr (model-route, with the class and a count only); when routing itself fails, the line is marked route-failed and carries no error text. When neither a routed model nor the configured one may receive the work, it does not start and nothing is sent: a background run fails with a sentence naming the class, saying nothing was sent and what you can change, and a task is refused before its worker starts, with an audit record that names only the model and the class.

When a message is not sent

The ceiling is a hard limit on what a model is sent, not a routing preference. One check runs immediately before every send, against the model about to receive it, however that model was chosen. It enforces confidential and secret only: each of those a request carries must be allowed for that model. public and internal steer routing and what context is gathered, but never stop a message, so a profile limited to public still holds an ordinary conversation.

A message that carries confidential or secret data the chosen model may not receive is not sent, and Clark does not move it to another model for you. The reply says which class stopped it, that nothing was sent, and that your message and model choice are kept, and it says what you can change:

In English it reads, for example: “This message carries confidential data, and {model} may not receive confidential data, so nothing was sent to the model. Your message is saved and your choice of model is unchanged. To continue, choose a model that may receive confidential data (such as one that runs on this machine), allow confidential for that model in Settings → AI & Routing, or send it again without that part.”

If the model's ceiling could not be read, the reply says so instead of naming a ceiling; an ordinary message still goes, and one carrying confidential or secret data does not. When a provider refuses a turn and Clark moves to the fallback model, that model is checked the same way; if it may not receive the message, you read both why the chosen model did not answer and why the fallback was not sent the message. Each refusal writes one line to stderr (model-send-blocked) naming the class and the model, never the text.

Credentials are refused by default. A profile with no list receives everything but secret, so a credential-shaped string (an API key, a password, a bearer token, HTTP Basic credentials, a SendGrid key) is refused to a third-party model rather than sent. Obvious placeholders such as your_api_key, changeme, example or xxxx are not treated as credentials; a value with a digit, or any other real-looking value, still is. The credentials in a URL such as postgres://app:<password>@db.example.com are not read as an email address.

The check covers everything a turn sends: your words (including the text of attached text files), the recap, the memory brief, references, project instructions, earlier messages and what is on screen, a sentence steered into a running reply, and every tool result and tool error fed back to the model. It covers a background run's request and the context it retrieves, and a task's goal and project instructions before its worker starts. Three parts are handled without stopping the message:

Scope. The boundary does not cover image content, which is not classified (an image is dropped only with a withheld result); text the agent composes into its own system prompt, such as the working directory, a context file's path and tool descriptions; native Pi extensions, which are trusted code on your machine; or what a session already holds from earlier turns when a profile's ceiling is narrowed while it continues. CLARKCANT_CONTEXT_PLANNER=off turns withholding off, search_history included, but the check still runs, so a turn whose recap, memory or history carries a class above the answering model's ceiling is refused rather than sent. Routing by data class applies with the planner on or off. The ceiling decides what a model may be sent, never which tools it may call.

Project instructions

A project can keep instructions that apply only to part of it. Your node reads them only from a project inside a folder you already granted: .clarkcant/instructions.json holds up to 32 rules, and each included name is the file .clarkcant/instructions/<name>.md.

{
  "version": 1,
  "rules": [
    {
      "when": { "path": "src/payments/**", "operation": "write" },
      "include": ["payments"],
      "pin": false
    }
  ]
}

Instructions reach the model as project data: a header says they come from the project's .clarkcant files, are neither your words nor your node's, and grant nothing. Each is wrapped in a tag carrying a code your node draws once per session (a rebuilt or handed-off session gets a new one) and states once, in its own guidance at the start of that session, as the only code that marks project guidance; a task worker's brief names its own code. An instruction cannot close its own block, even with a tag written in fullwidth or look-alike characters, split by invisible ones, decorated with combining marks or spaced out after < or /, and a project folder's name cannot break the tag that names its source, and a block copied into a file or a tool's output carries a code your node never stated to that session, unless the session itself repeated it. This is a signal the model reads, not an enforced boundary: the execution policy decides what any action may do, and instructions grant nothing either way. There is no opt-in step: a project's instructions apply because you granted its folder, and every effect still goes through the execution policy. Instructions are labelled like any other block and withheld above the model's ceiling. Limits: 8 names per rule, 4,000 characters per instruction, 6,000 per turn and a 64 KB rules file. A file your node cannot use is reported once on stderr (instructions-invalid, with the folder name and a reason: too-large, not-json, shape or unknown-version) and changes nothing. CLARKCANT_CONDITIONAL_INSTRUCTIONS=off (default on) turns this off.

Instructions from a package

An installed package can carry rules in the same contract through an instructions facet, which needs "schemaVersion": 3 in its clarkcant.json; a package declares at most one. A node that knows only version 2 refuses such a package as a whole rather than misreading it. Installing the package applies none of its rules:

When a conversation gets a fresh session

A conversation keeps one model session until it fails, is evicted or changes to a model that cannot take it over (below). CLARKCANT_SESSION_POLICY (default off) decides at each turn whether to keep it:

A rebuild starts a fresh session briefed by the planned recap, restates instructions and tools, and leaves the conversation itself untouched. If the fresh session cannot be created, or the policy step fails, the turn continues on the old one. A message sent during a rebuild waits for it and lands in the new session, and Stop during a rebuild discards the new session and sends nothing. Any other value is off. The thresholds are judgements from a scripted cost simulation, not live measurements.

When you change the model

Changing the model or the thinking level never cuts off a reply Clark is writing: the change applies from your next message. Usually that message carries on in the same session on the new model, which keeps everything the session already holds, so nothing is briefed again. The session is kept only when the new model may receive every data class any model the session has run could, and nothing was left out of the session that the new model may receive. Otherwise, after a provider has refused a turn in that session, when you go back to a model's default thinking level, or when moving the session fails, your next message starts a new session on the new model, briefed with a recap of the conversation narrowed to what that model may receive. Clark never answers on the previous model instead. If the switch fails, the turn says so in your language and the conversation is left as it was, for example: “Could not switch this conversation to {provider/model}: {reason}. Your message is saved and the conversation is unchanged. Retry, or choose another model.” Local file paths are removed from the reason. If getting ready to answer takes longer than the turn's time budget, the turn stops with “Could not get ready to answer within {N} s, so this turn was stopped. Your message is saved. Retry, or choose another model if this keeps happening.”

How long a turn may run

By default a turn has no time limit: it runs until it is done, and you can press Stop at any time. To cap it, choose 5, 15, 30 or 60 minutes in Settings → AI & Routing → Thinking and time. An operator can also set CC_MODEL_MAX_WALL_CLOCK_MS. A turn that reaches its cap stops and says so in minutes; your message is kept.

Where to next