# BoardAgent

Work through your own agent. Keep the board’s canonical records, permissions and confirmations in one self-hosted service.

BoardAgent is a self-hosted, MCP-native board-governance system of record. Directors,
observers, management, and the secretariat work through their own MCP-capable agents.
BoardAgent has no governance portal and runs no server-side AI: it stores canonical
machine-readable records, enforces procedure and authority, and produces tamper-evident
evidence.

> **Status on 15 September 2026: private hardened beta, deployed for a supervised synthetic trial.**
> Candidate `57f1638` passed the full local regression net (tiers T0 to T9, 3,306 test executions,
> 100 % mutation score on the deterministic kernel, clean image scan) and the native Linux
> qualification including the frozen performance targets, and was installed on a synthetic VPS by
> the preserving-upgrade procedure with a rehearsed backup and public HTTPS/OAuth verification.
> Four real people then enrolled with passkeys and completed onboarding through their own agents,
> a charter was activated as a governance profile with clause citations, and a written resolution
> was circulated and put to a vote. That is the state of the evidence; it is not a public
> production release and no security certification is claimed. Use synthetic information only.

What that trial also showed, honestly: binding acts (votes, invitations, governance changes)
are confirmed through an MCP elicitation form that today only Claude Code renders, so other
clients can read the board but cannot act on it; the administrator step-up needs a real
passkey within ten minutes and a browser that keeps its session can defeat it silently; and
the pre-upgrade recovery rehearsal decrypts the whole WAL archive. These are the first items of
[the roadmap](docs/ROADMAP-NEXT.md). The [verification register](docs/VERIFICATION.md)
identifies implementation and test pointers; [known limitations](docs/KNOWN_LIMITATIONS.md)
and the [readiness plan](docs/execution/MINING-READINESS.md) distinguish historical proof,
pending work and actual human acceptance. The [execution record](docs/execution/STATE.json)
retains an earlier consolidated checkpoint. Machine-specific values in the working records
under `docs/execution/`, `docs/handoffs/` and `BUILD_LOG.md` are replaced by placeholders such
as `<vps-host>` in this public tree.

BoardAgent is not a qualified electronic-signature service, a notary, legal advice,
proof that a person understood a record, or a security certification. Your agent
presents information; BoardAgent records exact information and confirmations. Each
person remains responsible for reviewing the content and securing their agent and local
copies.

## What it does

- Keeps one organization and its boards, members, governance profiles, rules, documents,
  meetings, transcripts, minutes, votes, proxies, questions, submissions, proposals, and
  tasks in PostgreSQL.
- Applies role, board, recusal, confidentiality, lifecycle, and exact-resource checks on
  every MCP operation.
- Requires one-use, server-attested confirmation for binding human acts.
- Preserves append-only audit events, signed checkpoints, vote certificates, encrypted
  exports, backup receipts, and restore receipts.
- Supports built-in WebAuthn/TOTP authentication and pre-linked OIDC identities.
- Runs a separate least-privilege worker for notifications, exports, deadlines,
  checkpoints, retention of operational ephemera, and recovery jobs.

## Deliberate boundaries

- No server LLMs, embeddings, OCR, conversion, document extraction, or content-check API.
- Only canonical Markdown, plain text, and declared versioned JSON are accepted.
- PDF, PowerPoint, Word, images, scans, archives, and binary redlines are rejected.
- No governance UI and no email/SMTP workflow.
- The browser is for enrollment, authentication and onboarding attestation; board work
  and binding action confirmations use the person's supported MCP client.
- No physical purge of governance, content, audit, consent, or evidence records in v1.
- Webhooks are contentless wake-ups, disabled by default, and restricted against SSRF.
- A software client name is not identity. Deployment restrictions use exact server-issued
  client IDs or exact Client ID Metadata Document URLs checked through HTTPS and metadata
  validation. Metadata deadline and cleanup repairs have focused regression coverage;
  public DNS, HTTPS port 443 and actual provider acceptance remain unqualified.

The frozen implementation contract is [BUILD_PLAN.md](BUILD_PLAN.md). Security and trust
boundaries are in [SECURITY.md](SECURITY.md); deployment is in [DEPLOY.md](DEPLOY.md).

## Architecture

```text
MCP client / human browser
          |
       HTTPS
          |
        Caddy
          |
  BoardAgent server ---- public certificate verifier
          |
   private backend network
          |
      PostgreSQL <---- least-privilege worker
          |                      |
   audit/evidence          exports/notices/jobs

Operator CLI ---- migrations, bootstrap, keys, verification, backup/PITR/restore
```

The supported v1 deployment is one organization on one Linux VPS, one BoardAgent server,
one worker, PostgreSQL 18.6, and Caddy. Runtime containers run read-only, as non-root users, with
dropped capabilities and separate database principals. Horizontal scale, multi-tenant
hosting, public cloud control planes, and automatic failover are outside the frozen
profile.

## Exact development toolchain

- Node.js `24.20.0`
- pnpm `11.24.0`
- PostgreSQL `18.6`
- Docker with Compose v2 for runtime and integration verification

Direct dependencies are exactly pinned. Do not silently substitute toolchain versions.
The recorded provenance is under `artifacts/provenance/`.

## Start here

| Reader                   | Guide                                                                                                |
| ------------------------ | ---------------------------------------------------------------------------------------------------- |
| New user                 | [User manual](docs/MANUAL.md): connect, understand a receipt and get help                            |
| Company administrator    | [Administrator manual](docs/manuals/administrator.md): accounts, authority, charter and succession   |
| Secretary                | [Secretary manual](docs/manuals/secretary.md): enrollment, meetings, votes, minutes and actions      |
| Board member             | [Board-member manual](docs/manuals/board-member.md): read, ask, vote, use proxies and sign minutes   |
| Agent/client implementer | [Agent guide](docs/AGENT_GUIDE.md) and [generated surface reference](docs/SURFACE_REFERENCE.md)      |
| Technical operator       | [Deployment](DEPLOY.md), [security](SECURITY.md) and [31 operator runbooks](docs/runbooks/README.md) |

### Evaluate with Mining Exploration Co

The [Mining Exploration Co fixture](demo/mining-exploration-co) is a fictional
charter and exercise pack for one nonvoting secretary and three equal-weight board
members, with a separate setup administrator. Follow its
setup instructions and inspect actual execution receipts before assuming an
instance or account exists. Creating a fixture, installing a service, issuing an
invitation, registering a passkey and completing onboarding are separate steps.
Local and VPS installations need separate database state and credentials.

A secretary account does not automatically have a vote, company-administrator
powers or a server login. The manuals explain the additional setup administrator
and the supported handoff to the intended board seats. Use only this synthetic
pack during the current evaluation. A scripted authenticator or automated ballot
belongs to a test fixture; it cannot establish an actual person's acceptance.

### Build and check a local checkout

Obtain an exact source checkout or reviewed source archive. With the exact
versions listed above, run from its root:

```sh
corepack pnpm install --frozen-lockfile
corepack pnpm verify:phase0
```

`verify:phase0` checks static integrity and provenance; it is not a running-system
or database qualification. Some provenance/vendor/browser prerequisites are
separate from dependency installation: follow [tests/TESTING.md](tests/TESTING.md)
when a check identifies missing evidence. Do not skip a check to make setup pass.

For a disposable local installation, follow the
[Mining Exploration Co setup](demo/mining-exploration-co) with reviewed
`.env.example` values and synthetic data. Build the server/PostgreSQL images
before starting services. The default server listens on loopback port 8787; it
is not a browser governance interface. The production
profile uses Caddy HTTPS and separate operator/runtime principals. Use the
[bootstrap procedure](docs/runbooks/02-bootstrap.md) for its one-use operator
command; do not run production bootstrap through the server's database role.

Keep enrollment links, activation codes, OAuth credentials, secrets and private
operator inputs outside source control. Do not publish a deployment's `.env`,
private login guide or captured account handoff with the example pack.

## First agent journey

After your separate account is registered and activated, connect your agent to the
exact HTTPS resource ending in `/mcp` supplied by the operator. A setup administrator
and ordinary secretary are separate responsibilities; follow the account handoff in
the [administrator manual](docs/manuals/administrator.md). A cautious first session is:

1. Connect and log in with your normal scopes; until your onboarding is current the server
   issues an `onboarding:read` token and says so in the token response. Call `whoami`,
   then `list_my_boards`.
2. Run `onboard-boardagent`, inspect `get_onboarding`, complete your own attestation;
   the next token refresh (within fifteen minutes) or reconnect carries your ordinary
   scopes.
3. Read `get_my_board_snapshot`, `list_my_updates`, and `list_pending_actions`.
4. Use strict read tools before any write. For a binding act, inspect the staged exact
   content and complete the server-driven confirmation yourself.
5. Rehearse an entitled read, then follow the role manual for a synthetic workflow.
   An eligible member chooses their ballot; the secretary opens the vote and follows
   its configured close mode. Keep automated fixture acts and actual human acts separate.

The full role-by-role guide, safe prompting rules, content formats, and confirmation
workflow are in [docs/AGENT_GUIDE.md](docs/AGENT_GUIDE.md). BoardAgent deliberately has no
shared semantic “brain”: [ADR 0005](docs/adr/0005-agent-owned-derived-memory.md) defines why
canonical shared records stay server-side while optional derived memory stays under each
person's agent/client control.

## Verification and release labels

The regression net has tiers T0–T10. The private-beta command runs deterministic tiers
T0–T9; public release also requires independent external review at T10.

```sh
corepack pnpm verify:private-beta
```

The command must run against one unchanged source tree. A passing historical command is
not evidence for later edits. Do not bless or alter regression-net state as part of a
build. See [docs/VERIFICATION.md](docs/VERIFICATION.md) for the 94 original security
requirements and eight approved administrative additions, their proof status and exact
tests, and `tests/TESTING.md` for test execution. A full private-beta or release
run also writes `gate3-manifest.json`, `evidence-ledger.json`, `outcome-comparison.md`, and
`HANDOFF.md` beside its result receipt. The legacy `gate3` filenames remain for
compatibility. These files collect candidate evidence; they do not invoke the retired
Architect/Gate workflow or approve a release.

The Mining handover also needs a persistent local installation and a separately verified
VPS installation, each with the intended people, reviewed charter, working custody and
actual role-by-role acceptance. The owner publishes the reviewed repository to GitHub
after checking its exact contents; a GitHub push does not qualify or deploy the product.

## Contributing and reporting problems

Use synthetic reproductions and keep changes scoped to the stated defect. Preserve
immutable migration history, generated registry contracts and failing evidence. Run
focused checks, then the required full qualification on a clean final candidate.
The [build contract](AGENTS.md), [build plan](BUILD_PLAN.md) and
[verification instructions](tests/TESTING.md) explain the repository requirements.

A useful nonsecurity bug report identifies the exact commit/image, environment,
nonsecret request reference, expected result, observed result and minimal synthetic
steps. Report vulnerabilities privately under [SECURITY.md](SECURITY.md). Do not
post real board records, invitation URLs, private keys or access tokens in issues.

## Operations and security

- [DEPLOY.md](DEPLOY.md) — supported topology, secrets, initialization, upgrades, and
  recovery.
- [SECURITY.md](SECURITY.md) — threat boundaries, reporting, residual risks, and known
  limitations.
- [docs/AGENT_GUIDE.md](docs/AGENT_GUIDE.md) — agent onboarding and safe operation.
- [docs/SURFACE_REFERENCE.md](docs/SURFACE_REFERENCE.md) — generated closed MCP, HTTP,
  CLI, resource, prompt, and event inventory.
- [docs/runbooks/README.md](docs/runbooks/README.md) — operator procedures and evidence
  expectations.
- [docs/THREAT_MODEL.md](docs/THREAT_MODEL.md) — 63-threat control and proof matrix.
- [docs/KNOWN_LIMITATIONS.md](docs/KNOWN_LIMITATIONS.md) — release blockers, intentional
  boundaries, and residual-risk owners.
- [docs/adr/](docs/adr/) — accepted architecture decisions and tradeoffs.

No deployment, remote push, external-review contact, or sharing of real board data is
authorized by Gate 2 alone.

BoardAgent is licensed under the [MIT License](LICENSE). Report suspected vulnerabilities
through the deployment's private security route described in [SECURITY.md](SECURITY.md),
never by posting board content or credentials publicly.