Window

A tour of every screen in the app, from the home page and chat to the project tabs, the ticket, asset, run board and commit pages, and the foot line, with where each is explained.

The window is the app's one page. Its pages that belong to no project are listed in GLOBAL and a project's tabs in TABS. Every screen is covered below, in the order of those two lists, then the ticket, asset, run board and commit pages and the foot line that shows on all of them.

The home, chat, search, settings, ticket, asset, run board, commit and foot sections follow an earlier page-by-page read of the window's code (frame.js, mission.js, tickets.js, settings.js, assets.mjs). That read has not been repeated line by line for this page: not checked. The stats, breaks, areas, docs, discord and setup sections were read from their own files.

01home#

The lobby. It lists every saved project, each opening on its manager. A row shows:

• the manager: "manager pinned" or "no manager yet". A project has none until one chat is pinned.
• the gates waiting: "N gate(s) waiting" or "0 at a gate". A gate is a point where a run stops for the operator (see gates).
• "N running": runs going now in that project.
• "N side chat(s)": the chats of the project other than its manager (see chats).

"general" lists the chats that belong to no project.

02chat#

One chat opened as the page. The thread carries the cards the desk draws (see cards):

• a gate card for a run stopped for a decision. Its state is waiting, approved or sent back. It shows the review (review N/M is how many of the done-when items the reviewer found met; "your review" means no model reviewed and the items are yours to check), the checks (checks N/M passed of those run), the doubts the worker raised, the files changed, how many times the work was sent back, and the time from the run start to the gate. The buttons are approve and land, and send back with a reason.
• a launch card with a go button, and its result line once pressed (see launch).
• proposal, permission and question cards, whose labels are plain buttons and sentences.

A chat that is a project's pinned manager carries a diamond mark and the word "manager".

03chats#

The list of all chats, and the same list as the project tab chats. Each row shows its title, whether it is also open in the side dock, how many runs were started from it, when it started and when it last moved. The archived toggle swaps the list for the archived chats. The row buttons open a chat as the page or in the dock. "keep" stops a chat being cleared on its time limit. See chats for archive, clear, compact, move and trash.

04system#

The machine under live runs, with a foot list "what the numbers mean" taken from the glossary words. See glossary.

• Headline cards: live runs, memory in use, and the host's totals.
• Per live node: the memory, processes, cpu, cpu time and run time its unit holds now, against the limits the attempt was admitted with. "near" is 80% or more of a limit; past it the attempt is killed. cpu is never marked near, since a unit at its quota is slowed, not killed. "ran" is what the node's finished attempts used, from the run's journal. "not running" and "not contained" say there is nothing live to read (see containment).
• Live totals: memory, cpu and processes of every running unit added up, beside the host's memory, available memory and cpus.
• "next run" and "room for another": what another run would be admitted with, and whether available memory holds it.
• Disk: what smith keeps (patch roots and work clones), each counted once.
• The core (its version and port), the conductor, the discord bridge, each agent runtime (ready, not installed, or can't start with the reason) and the search index (documents, skipped and failed per source, and when each last ran).

05stats#

The stats page reads three index answers when it is opened, and then more for its other sections. The numbers are the cross-run index's, the same ones the conductor reads with its run_stats tool. Each section has a chat icon naming the metric to ask about.

• end states: how each run in the journals ended, with a count, a share and a plain line per state: landed, failed, stopped, rejected, running, finished without a gate, waiting on the operator and stuck (PLAIN). Stuck is no end and nothing in the journal for an hour.
• first-time approval: of the runs that reached a gate, how many got through without being sent back. Four rows (approved at the first gate, clean through, the review sent it back, the checks sent it back) and a by-template strip. Gate decisions carry no actor, so an automatic approval counts as the operator's (ACTOR_CAVEAT).
• per day: the last 14 days, by the UTC day a run started: runs started, landed, failed, stopped, first gate yes, review said no, the operator said no, and list price.
• time per stage: where a finished run's time goes, the machine working or a gate waiting. Medians and the slowest 10% per stage (intake, plan, work, checks, review, close and the rarer ones;).
• check failures: per check, runs, failed, split into the machine's fault and the code's, failed then passed, median and slowest 10%.
• each model in each role: calls, median, list price, per call, failed, tokens and how its work went.
• not in the journal yet: what the page would show, and the field or ticket each one waits on (NEEDS).
• spend: what the models cost in a window. Switch the window between today and week, rank by cost or tokens, sort the recent runs by a heading (10 rows a page), and open a run's spend by node in a drawer. The price is a list-price estimate; the subscription is what is billed (BASIS). A figure a runtime did not report reads "not reported", never 0.

06breaks#

The what-breaks page reads three index answers (failure, miss, stuck) when it is opened. Each section has the same chat icon.

• failures by cause: the runs that failed or were stopped, by the first thing that went wrong, with failed and stopped counts, the day of the latest, and chips that open the latest runs' boards.
• reviewer misses: the reviewer accepted, then the operator sent it back at the gate. It counts misses of the accepted reviews and lists when, which reviewer, the ticket, and what was said at the gate. Gate decisions carry no actor, so an automatic send-back counts as the operator's (MISS_CAVEAT).
• stuck runs: the runs unfinished now (running, waiting on the operator, or stuck after an hour of quiet) and every stall of 20 minutes or more outside a gate, with the event that woke the run (WOKE; stuck).
• not in the journal yet: doubts that came true, gates open overnight, and who stopped a run (NEEDS).

07settings#

The global settings page. It holds the settings rows (each can carry a "?" link to the page that explains it), the roles, and the backups. See desk-json and harness-json for the files behind it.

• roles: who a side chat or run node is, with its words, model, skills, tools and assets. "live chats" and "live nodes" say where a role is working right now (see roles).
• backups: everything smith keeps on this machine, copied to a dated folder, with a schedule, snapshots (open one for its parts and to restore it), the tickets database copies (one per day) and "back up now" (see backup-restore).
• "go back to the previous version" restores the earlier saved settings file.
• "source files" shows the raw settings files as JSON.
• a system area where a release can be checked for (; see updates). What else it holds: not checked.

The project tab settings holds the same kind of rows for one project, and its colour has a "reset to default" button that puts back the one smith picks.

08search#

A search over runs, chats, files, assets, skills and memory (see memory-and-search). A scope line says where it looked: everywhere, or in this project. Kind chips show the source of each hit and a count, with a plus when there are more. The +1 and -1 buttons tell the tracker a hit was helpful (ranked higher) or stale (ranked lower).

09setup#

The first-run page. It walks a fresh install through ten steps and opens by itself on a first launch. Everything about it is on setup.

10docs#

The built-in manual, the pages you are reading, drawn at #/docs. The same pages are served to the conductor by the docs desk tool and to a terminal by smith docs (see cli).

• The docs tool is read-only and answers from the manual built into this binary. With no arguments it returns the index (topic and one-line summary). With topic it returns one page, or one section with topic#anchor. With query it returns the pages and sections that mention the words. A page over 12,000 characters comes back as its first section with a note to ask for topic#anchor for the rest.
• A topic page shows the text with its headings, and a rail: the headings on this page, a line to cite it, the pages that link here, the ids the page covers, and the build it was written for.
• #/docs/search takes words, a field name, a file name or an error's own words. Every word you type must appear as typed, in any case, in a heading or its text. With no hit it offers to ask the conductor.
• #/docs/changes is the changelog: every release newest first with the ticket each change closed, the installed one marked, and newer ones on the update channel with an install button. A build from source has no changelog baked in. The changelog tool is described in updates.

changes and search are reserved, so no topic can use those names.

11manager tab#

The project's first tab. With a manager pinned it opens that chat as the page, so the chat cards above apply. With none it shows the project's chats list. The diamond mark and the word "manager" show beside the manager chat, and side chats the manager started carry a "delegated by" tip (see chats).

12runs tab#

The project's runs, newest first.

• Filter chips: all, done, stopped, failed.
• Groups: needs you, live, today, yesterday, earlier.
• A row shows the status word (done, failed, stopped, running, needs you, paused), "took" (time between the run's first and last journal event), a list-price figure, tokens in and out, the gate (approved, waiting and so on), and a stage bar with one segment per step. "↺N" on a segment means the step ran N rounds.
• Chips show the run's short id, its ticket, its template when it is not ticket completion, and its project.

A row opens the run board. See runs.

13tickets tab#

The project's tickets, from the tracker (see tickets). The toolbar has saved views, an "everywhere" switch that lists the ready tickets of every project, and a group-by (status, phase or priority). Phases show as active or finished, with the open tickets and the phase's brief. A row shows its status, "blocked by N" or "ready to start", priority, labels and wave. The wave orders work inside a phase: lower waves go first. A ticket opens on its page.

14areas tab#

A project's areas: named sets of paths, each with its own manager, brief, checks and fence (HEAD_LINE). An area's row shows its manager line, such as "manager pinned", the model and the count of side chats, or "no manager yet" (managerLine). The editor has:

• name: what it is called in the menu, on tickets and on cards; lowercase, no spaces.
• paths: one glob a line; a leading ! leaves a file out. A ticket's area is the one its paths sit in, and a run's checks follow the paths it touched. A dry run shows what a draft matches without saving.
• brief: what the area's manager knows, and what every run of an area ticket reads after the project's brief. The limit is 2,000 characters (BRIEF_LIMIT). See projects.
• checks: what must pass when a run touches the area's paths. A run gets the checks of every area it touched, plus the project's (FIELD_LINES).
• fence: what happens when a run of another area's ticket edits this area's files. It is flag (flag it at the gate), hold (approve waits until the files have been looked at) or off (say nothing). It never stops a run. In an overlap neither fence trips and both areas' checks run (FENCES, FENCE_LINE, OVERLAP_LINE).

The fields of an area are listed in projects and harness-json.

15assets tab#

The project's assets: the members, with "make main" (the main asset leads the list and is shown on cards) and "remove" (takes it out of this project only). "import an asset" adopts an existing folder or makes a new asset and adds it to the project. See assets.

16discord tab#

The project's discord page, in the menu only while the project's discord box is on. It binds the project to a server and has sections for the server (and whether it reaches the desk now), the channels, the commands, three steps to bind and the members. The bridge's state shows as connected, partly connected, not connected or not bound yet (STATE_WORDS). See discord.

17chats tab#

The project's chats: the same list as the chats page, narrowed to the project, with the manager marked.

18project settings tab#

The project's settings: its colour, roles, and the rows that override the global ones. See projects.

19ticket page#

One ticket. It shows the ticket text (with a markdown preview while editing), the column, phase and id, and what was learned and the testing evidence once it is done. The facts are status, blocked or ready, priority, labels, "depends on" (the heading says how many are still open), "blocks", due, for, phase, wave, and who filed, closed and updated it. Actions open a launch card for it, start a chat about it, or move its column. Below are the runs started for it with their status and a link to each board, the assets tied to it, and the comments; a posted comment cannot be edited. See tickets.

20asset page#

One asset: a saved file, folder, repo or set of notes kept across runs, and its versions. It shows "now" (the version the runs read), the size of this version and of all versions, the engine (smith's own snapshots, a git repo, or notes and a url only), the git facts, the folder, the projects it is in and when it was last used. The actions are save version, re-derive and accept a suggestion, "plug into a run", and retire. Older versions are folded in a newest-first timeline, and "used in" lists each run that plugged the asset. See assets.

21run board#

The board of one run: its nodes, the cords between them, and a rail. See runs and nodes.

• A node shows its status (running, waiting, waiting for limit, failed, done, idle, and ×N for the rounds it ran), time, tokens, and its model and list-price cost so far.
• The rail shows HOW (the planner's steps), DONE WHEN (what the reviewer checks before the operator is asked to approve), THE PLAN with how many items are met, CHECKS SMITH RAN, and the run's tickets.
• A cord is a line from one node's outlet to another's inlet; a baton is the set of fields a node passes on; a hop is the count of cords a message has travelled, and a run is sent to the operator when it passes the hop cap. See glossary for these words and the names the page may use for them.

22commit page#

One commit that landed: its message and the files it changed.

23foot line#

On every page, a line of facts with a tip on each: "N live" (runs going now, across projects), "checks N" (checks run before review), "N ahead" and "N behind" (commits against the project's upstream), and "core" (the desk core this window talks to).