App Boards & the Hub

An app board is a board that represents one repo. Any board becomes one when you bind a repo as its governing Code Plugin source.

What binding a repo changes

When you add the governing binding, the board converts, shows "This board is now an app board", and makes the hub its opening screen. It gains aspects, analysis coverage, work items developers can pull, and compiled skills. To go back to a normal layer, use Remove app on the hub; see Removing or deleting an app.

The six facets

An app board tracks six facets:

Expand

The tab strip doesn't map one-to-one onto that list. Insights have no tab, and two tabs aren't facets: Pages is a screen over the ui.pages aspect, and Changes is the repo's diary. The board tree lists each board's tabs.

The hub, card by card

The hub opens with the attention queue: what needs a decision now. It lists draft work items, conflicts, work items a developer sent back, work items that drifted, and implemented work items no push has proven yet. It also lists scheduled runs that stopped or went quiet, repos that went quiet or never pushed, and a new app not ready to build. Flagged changes nobody has reviewed and insights awaiting review are there too.

Each row has its action. The Hub tab's badge counts the same rows, and an agent reads the same queue through get_hub_status.

Below the queue, while the app is a side of an open comparison, In comparisons runs across the full width. Each comparison gets a cell: its name, the app's part in it, its verdicts as a bar and its headline, such as 9 of 14 contracts kept. An app that replaces another reads Replaces Legacy Orders, and an app being replaced reads Compared with Orders API. In a release check it reads Beta on develop compared with live.

Select one to open it on the root board's Comparisons screen. With the app in no open comparison, the card isn't shown.

Then Changes sums up this app's weeks. A sentence says what leads, and a line counts the commits and the share naming a coding agent. A column per week stacks its entries by kind. Under them come the filters and the weeks' entries, flagged and breaking changes first, with the change rules each hit. Worked on names the nodes the listed weeks' commits landed on, busiest first. The From other apps filter lists the changes in other apps that reach this one, such as a renamed endpoint this app calls.

Beside it, Architecture is this board's canvas painted with those weeks. Each node glows with its commits, rings where an entry changed a contract through it, and marks a broken boundary rule. The entry you point at or select lights the nodes it landed on, and Replay the weeks steps every diary card through them.

An entry's View detail reads it in full on the Changes screen. Its Timeline view lays the weeks out on their days, with a lane per node the work landed on and Across the app for entries tied to none. To keep the timeline and the selected entry on the hub, add Diary timeline and Diary entry from Add widget. The Root Hub covers both.

1. 1

   In comparisons

   Shown while the app is a side of an open comparison, with its part in each.

2. 2

   Worked on

   Worked on names the nodes the listed weeks' commits landed on, busiest first.

3. 3

   Architecture

   This board's canvas painted with the listed weeks; the entry you point at lights the nodes it landed on.

1. 1

   From other apps

   From other apps lists the changes in other apps that reach this one.

2. 2

   Architecture

   Beside it, Architecture is this board's canvas painted with those weeks.

Below them, the Contract surface card draws the app as a box with its ports. They are what it Answers (its endpoints), what it Calls, what it Publishes and Listens for, and what it Stores. Each port names the apps at its far end today, such as who calls an endpoint, read from the calls and events adopted across the system. A port adopted in the period is marked new, and the line above the box gives the period's contract answers from Changes. Until the app has adopted any of these aspects, the card names the /aspects command that adopts them.

The cards outside the diary sit in three groups, named at the top of each card: Inbound, The map, and Outbound. Cards beyond the defaults are under Add widget; Layers is offered only when the board has layers below it.

You can also add an About card with the board's own description. On a wide screen, Customize in the hub's header lets you move, resize, add and remove cards; the attention queue always stays. Your layout is yours alone, and it applies to every app hub in the workspace. A layout you saved earlier keeps your arrangement, with Changes and In comparisons added under the attention queue.

The period control in the hub's header sets the period the change cards count over, such as Shipped and the aspect figures. Change Cards covers each one.

Each card opens the matching screen. Each aspect kind can also have a card of its own, such as Endpoints or Boundaries, leading with its count and what needs a look; see Aspects on the hub. On an app hub, an aspect card whose kind an /aspects push changed in the period also shows how many items were added, changed and removed.

A card with nothing to show names the one step that fills it: a plugin command to copy, such as /aspects, or a button, such as Run an analysis. On a board no repo is bound to, a card that only the code plugin can fill asks you to bind the repo first. A change card that is empty in a short period while a longer one has changes offers to show the longer period instead.

Playbooks lists runs in progress first, then the guided tracks you can start from this board. Those are the setup guide and one track per common job, such as replacing a stale architecture document or planning a migration. Each row shows how much of it the workspace already satisfies.

Bindings and pulse

The Bindings card draws the board's bindings as a graph. Each binding has a pulse that shows how fresh its data is:

• live — something arrived in the last day
• quiet — one to seven days
• dormant — over a week
• never — the source is bound but has not pushed anything yet

Expand

1. 1

   The governing repo sits on top

   One source governs the board: the repo behind the app, joined by a solid line.

2. 2

   Every binding has a pulse

   A coloured dot and a timestamp say how fresh that source is: live, quiet, dormant, or never.

3. 3

   Reference bindings fan out below

   Context you watch but don't govern, on dashed lines. Each one can have a different freshness.

If a repo is dormant, sync may have stopped, a pipeline may have broken, or the branch may be inactive.

A repo that runs the code plugin on a schedule also gets a badge on its chip when its scheduled runs need a look. The badge reads Scheduled run stopped when the newest run stopped. It reads Last scheduled run, with how long ago, when no run has arrived for the workspace's threshold, 48 hours by default: the schedule may have stopped firing. Either one also puts a row in the attention queue; a stopped run's row names the reason and the fix, and View runs opens the repo's history.

A Sentry project binds like any other reference source: choose Add on this card, then Create New → Browse Providers, and pick the project. Its issues arrive every hour as draft insights on the app's node, on the board above this one. See Sentry insights.

Analysis coverage

The pulse tells you data is arriving. Analysis coverage tells you whether the board still describes the repo.

The code plugin plans the whole board tree from the repo's structure. Each planned board is a unit. The card counts units that are built, stale (built, but changed since), incomplete (the board fails its check or leaves files unclaimed), or unbuilt (planned, but not built).

The percentage is the share of planned boards that are built, rounded down; stale boards still count as built. One board out of thirteen reads as 7%, however many files it owns. A newly built top board starts low, and each drill-down raises the percentage by a visible step.

Three chips under the bar break the numbers down; hover one for the arithmetic.

• Boards is the headline: built boards divided by planned boards.
• Files is the true coverage: the significant files that sit under built boards, divided by every significant file in the plan. Each file belongs to exactly one planned board, the deepest one that covers it. The chip also lists what stays outside the plan: minor files, infrastructure and schema files, tests, excludePaths, coverage.ignore, and files with an extension the plugin does not count.
• Depth shows how deep the plan goes and whether analysis.plan.maxDepth capped it. A cap changes how many boards the plan has, so it moves the headline; it never changes the file total. analysis.plan.unitFloor is the number of significant files a cluster needs before it becomes a planned board.

A top board that owns a few dozen repo-level files can read 7% by boards and 2% by files at the same time. Both are right; they measure different things.

The card also shows the commit and branch used for the calculation. Only the counts leave the developer's machine; file-level detail stays local.

Architecture, Layers and Context boards

• Architecture is the canvas card: the diagram itself, painted with the diary's weeks, and the way back to it from the hub. Select it to open the canvas.
• Layers lists this board's direct children; the board tree is the whole hierarchy.
• Context boards lists the boards drawn alongside this one, such as the ones /discover draws.

Push sessions and footprints

Every plugin push records a push session on the binding: the push type, who pushed, and what it changed in one line. Who pushed is the person who signed the plugin in or generated its key, not whoever bound the repo.

The line is the sentence the plugin's agent wrote at /sync or /aspects, such as "Now snapshots baskets to a new table before checkout". A push with no sentence shows its type and counts.

Open a session to see its footprint: created or touched items, grouped by facet. Binding history and session footprints have shareable URLs.

Its What changed section says which change period the push landed in, such as Landed in the week of 6 October. Select it to open that repo's diary entries for the week on the Changes screen: each piece of work, who did it, and the change rules it hit.

A binding's history also lists its Scheduled runs above the push sessions. Each run shows its outcome and, if it stopped, the reason and the fix, and totals what its pushes changed. A push made by a scheduled run is marked Scheduled.

The root hub

Your root board is the system map, not an app board: repos bind to the system layers beneath it. Once app boards exist there, the root opens on its root hub.

The first time you open the root board in an organization, it shows three short diagrams of the root board and apps in place of the hub or the canvas. Explore each diagram to unlock Next, then choose Open my root board. The diagrams don't come back after that; Getting Started, in the menu under your name at the bottom of the sidebar, shows them again.

Keep that shape even with one repo: create a system node and make that layer an app, so the root is ready for more apps later.

The root hub opens on Fleet attention whenever anything waits on a person, and Comparisons while a comparison is open. Then comes Changes: the pieces of work across every app in the hub's period, flagged and breaking changes first, beside Architecture, the root canvas painted with them. Point at an entry to light it on the root canvas and ring the boards it landed on in the board map. View detail reads it on the Changes screen. The Root Hub covers reading it.

The other cards on the root hub:

• Fleet attention lists the rows of every app's attention queue, the most urgent first, each named with its app. An insight filed on a layer inside an app counts toward that app.
• Comparisons, while any comparison is open, gives each open comparison a cell with its verdicts as a bar and its headline.
• Apps gives each app board a tile with pulse, last activity, coverage and outstanding-work badges. The tile's activity strip shows its pushes day by day, and the tan disc opens that app's hub.
• The System scorecard is a change card of the numbers that span apps.
• Shipped, under Add widget, is a change card that counts the period's completed work items across apps.
• Recent activity, under Add widget as Activity, lists pushes across apps, newest first: what each push changed, its app, and who pushed with which agent. Pushes to one app by one person on the same day fold into one row; two people never share a row. Select a row to open that app's hub with the push session's footprint open.

Customize works as on an app hub; the root hub's layout is saved apart from your app hub layout. The root's Changes tab holds every app's diary entries, with a picker to narrow them to one app.

The root hub doesn't pool per-app aspects, pages, layers, or skills. What passes between apps is the exception: the root's Aspects screen shows the events and calls between them. The System aspects card counts them and, on a wide hub, draws which system depends on which. The root's Add widget also offers a Boundaries card for the rules declared between systems. See Aspects Across Systems.

Connecting from outside

Each hub has an access button for its scope: Workspace agent access on the root hub, App agent access on an app board hub. Both are admin-only and offer terminal sign-in or a generated key.

MCP Access covers tokens. The Code Plugin covers repo bindings. Signing In & Credentials compares both.

One app, one repo

A board takes one governing Code Plugin binding, pinned to one branch, and an app board cannot contain another app board. Its layers describe the inside of one repo. The Board Tree explains the rule, what the bind control shows when you try, and which screen each kind of board opens on.

Removing or deleting an app

The bottom of an app board's hub has two actions: Remove app and Delete app. Both need board owner access, and you type the app's name to confirm. Both take effect immediately and bypass your working copy, so Discard can't bring anything back.

Remove app permanently deletes every aspect read from code. That covers database tables, API endpoints, pages and their screenshots, event channels, and authorization registries on the board and its layers. It includes anything you edited by hand, such as column tags. If you make the board an app again, the plugin extracts them afresh.

Boundary rules stay, since nothing in the code would recreate them. A plain layer has no Aspects screen, so the rules show again when you make the board an app again.

You can't unbind the governing repo or delete its source from the catalog directly; only Remove app does either. Reference bindings still unbind as usual.

Before either action runs, the dialog lists what it will remove, and it blocks you while there are unsaved or uncommitted changes on the app. A published board keeps showing the aspects it was published with until you republish or unpublish it.

What's next