A board is the human-facing, kanban-style view of your matters: a live picture of what is where. Opbox is always the source of truth and the board is always a regenerable view of it, so the board can never quietly become a second version of reality. Boards Sync Admin is the operator side of that promise: the controls that keep the projection honest, manage the link to an external issue tracker where one is configured, and resolve the edge where an agent and a person share ownership of a card. When a board drifts, you reconcile it back to the matters in a single action rather than reconciling by hand.
What it does
One source of truth, the board as a view. The matters in Postgres are the record; the board is a projection of them. Every card on the board traces back to a real matter, step, or gate, and the projection is rebuilt from that record rather than maintained as an independent copy. Because the kernel always wins, a disagreement between the board and the matters is resolved in the matters’ favour, never the other way round.
Tenant-wide reconcile with a drift report. Re-project every matter, step, and gate from the record into the issue set in one pass. The reconcile classifies what it finds - orphaned cards that no longer map to anything, missing cards that should exist, stale cards whose state has fallen behind - and brings each back into line, returning a drift report and a single audit event for the run. The operation is idempotent, so re-running it when nothing has changed is a safe no-op. This is the “the board can be wiped and rebuilt” repair: if the external view is ever lost or corrupted, you regenerate it from the matters.
Per-issue refresh. Where a single card has fallen out of step with its matter or step, reconcile just that one issue rather than the whole tenant. Like the full reconcile it is idempotent, so re-syncing a card that is already current changes nothing.
Projection lifecycle. A board’s projection can be detached without touching the underlying matters: stop projecting and the external view is dismantled while the record stays exactly as it was. The teardown is reversible - re-running the tenant-wide reconcile rebuilds the projection from the matters - and the board record and its audit history are retained either way.
The agent-to-human ownership edge. A card can be owned by a person or by an agent. Reassign a projected issue’s owner to move it across that boundary, for example to hand an agent’s card to a named human for review or back again. The reassignment is an ownership-only change: it moves who holds the card, with no effect on the work itself, and it mirrors how review reassignment behaves elsewhere in the system.
Principal resolution, both directions. An agent in the org and a user in the external tracker are two identities for the same actor. Principal resolution maps between them in both directions from one canonical write path: outbound, it renders an org agent as an assignee on a projected card; inbound, it resolves a tracker user back to the org principal so that the resolved principal’s own permissions govern what happens next. It maps two identities that already exist rather than introducing a new identity store, and re-resolving an already-mapped pair is a no-op.
Inbound webhook, governed like everything else. Where an external issue tracker is linked, its inbound webhook is handled through the same governed front door as any other call. The webhook handler resolves the tracker user back to an org principal so the change is applied under that principal’s permissions, and it is idempotent so a redelivered event does not double-apply.
Sync status and the issue roster. Read the current state of the projection and list the projected issues to see what the board is showing and whether it is in step. These are the read-side views an administrator uses to check health before or after a reconcile.
How you use it
Reconcile a drifted board. When the board and the matters disagree, run the tenant-wide reconcile. It re-projects every matter, step, and gate, reconciles orphaned, missing, and stale cards, and hands back a drift report telling you exactly what it corrected. Read the report, and re-run safely if you want to confirm a clean pass.
Check the projection before you act. Read the sync status and list the projected issues to see the current picture, so you reconcile from a known state rather than guessing.
Detach or rebuild a projection. Stop projecting to dismantle the external view without disturbing the matters underneath. When you want it back, run the reconcile and the projection is rebuilt from the record.
Hand a card between an agent and a person. Reassign a projected issue’s owner to move it across the agent-to-human boundary - for instance, to pass an agent’s card to a named reviewer. The work is untouched; only who holds it changes.
Map an agent to a tracker user. Resolve the principal so an org agent shows up as the right assignee on the board, and so inbound changes from the tracker are attributed back to the correct org principal and governed by that principal’s permissions.
The kernel verbs behind it
Each goes through the one front door: permission-checked, scope-checked, and audited before it runs. Because the matters in Postgres are the source of truth (see the data model), these verbs reconcile and manage a view, never a second copy of the record. These are the verbs most specific to the sync-admin side of boards.
board.regenerate- tenant-wide reconcile: re-project every matter, step, and gate from the record into the issue set, reconciling orphan, missing, and stale drift, with a drift report and an audit event.board.issue.sync- reconcile a single projected issue back to its matter or step; idempotent, so re-syncing a current card is a no-op.board.sync.status- read the current state of the projection.board.issue.list- list the projected issues to see what the board is showing.board.stop-projecting- dismantle the projection for a board without touching the matters; reversible by re-running the reconcile.board.issue.reassign- reassign a projected issue’s owner across the agent-to-human edge; an ownership-only change with no effect on the work.board.principal.resolve- map an org agent and a tracker user to each other, both directions, from one canonical write path.board.issue.webhook.handle- handle the external tracker’s inbound webhook through the governed front door, resolving the tracker user to an org principal so that principal’s permissions govern.board.get- read a board: what it shows and how it is configured.board.list- list the boards in the tenant.board.create/board.edit/board.publish- author, change, and publish a board (the authoring side; see Matter Management for templates and the board-as-matter-view).
See the full set in the board verb reference.