# Business Operations Agent Kit

[![CI](https://github.com/mkhragudo/business-operations-agent-kit/actions/workflows/ci.yml/badge.svg)](https://github.com/mkhragudo/business-operations-agent-kit/actions/workflows/ci.yml)

**[Try the zero-install live demo](https://mkhragudo.github.io/business-operations-agent-kit/)**

[Apply for a read-only adapter pilot](https://github.com/mkhragudo/business-operations-agent-kit/issues/new?template=adapter_pilot.yml) using public-safe, synthetic details only. Pilot evaluation starts with a reviewed read-only source contract and preserves `NO SEND / NO WRITE`.

The live walkthrough uses two fake businesses, makes no application network
requests after its static assets load, and preserves `NO SEND / NO WRITE`.

A public-safe starter for building the kind of operations copilot a business owner can actually use:

- “Where do we stand?”
- “What changed?”
- “Who has the ball?”
- “What are we genuinely waiting on?”
- “Does the inbox contradict the dashboard?”
- “Draft the next request.”
- “Which approved blank form should go with it?”

The kit is **not** a copy of a private business database. It is a harness-neutral policy core, a normalized evidence contract, an Agent Skill, and adapter patterns for Hermes, Claude, ChatGPT, and other MCP-capable systems.

## Why this exists

WIMPER Ops Agent is the validated private reference implementation: it proved that a chat can reconcile process state, dashboard records, email evidence, document state, ownership, drafts, and packet workflows.

This repository is the product extraction. It contains no WIMPER customer records, credentials, private messages, proprietary database paths, or attachment contents. All examples are synthetic.

## What works now

The starter exposes five read/prepare operations:

1. `list_businesses`
2. `get_business_status`
3. `get_missing_input_handoff`
4. `prepare_email_draft`
5. `prepare_attachment_manifest`

It exposes **no send or write tool**.

Every case-specific operation requires an explicit `business_id`. Every result is visibly labeled `NO SEND / NO WRITE`, includes evidence locators and a state fingerprint, and declares what did not happen.

## Try the zero-install browser walkthrough

[Open the live walkthrough](https://mkhragudo.github.io/business-operations-agent-kit/),
or open `demo/index.html` directly in a modern browser. The walkthrough uses
only the bundled synthetic results and makes no application network requests.

The checked-in `demo/demo-data.js` is generated from the same Python policy core
used by the CLI and MCP tools. Regenerate it after any core or fixture change:

```bash
.venv/bin/python scripts/build_browser_demo.py
```

The browser-demo contract tests fail if the generated asset drifts from the
executed synthetic workflows or exposes private source fields.

The demo shows:

- a sourced status report;
- one real task/document gap;
- one exact recipient;
- a proposed email draft;
- one explicitly approved blank-template attachment proposal;
- a second synthetic business where email and dashboard evidence conflict, causing the agent to suppress a duplicate request.

## Run the synthetic Python and MCP demo

One-command evaluator with [`uv`](https://docs.astral.sh/uv/):

```bash
uvx --from git+https://github.com/mkhragudo/business-operations-agent-kit.git \
  business-ops-agent demo --business harborlight-demo
```

Or clone the repository and run the full contract suite:

```bash
python3 -m venv .venv
.venv/bin/pip install -e '.[test]'
.venv/bin/python -m unittest discover -s tests -v
.venv/bin/business-ops-agent list-businesses
.venv/bin/business-ops-agent demo --business harborlight-demo
```

The default test suite includes a real stdio MCP transport test. To run the same transport probe by itself:

```bash
.venv/bin/python scripts/test_mcp_integration.py
```

Or:

```bash
./scripts/demo.sh
```

## Permission ladder

| Level | Capability | Starter default |
|---|---|---|
| 0 | Inspect status and evidence | Enabled |
| 1 | Prepare drafts and attachment manifests | Enabled |
| 2 | Create a staged provider draft or generated document | Designed, disabled |
| 3 | Send or update a source system | Disabled; requires a separate approval and receipt contract |

“Prepare an attachment” in this starter means produce a verified manifest entry. The model never receives attachment bytes or filesystem paths.

## Architecture

```text
Hermes / Claude / ChatGPT / MCP client
                 |
          shared Agent Skill
                 |
       five narrow read/prepare tools
                 |
       BusinessOperationsAgent core
                 |
         OperationsSource protocol
                 |
 email + dashboard + database + document adapters
```

The included `JsonDirectorySource` is a synthetic reference adapter. A real deployment replaces it with a connector that normalizes private evidence into the same bounded records.
The wheel includes the same synthetic fixture for a wheel-only demo; a contract test prevents it from drifting from `examples/synthetic`.

## Harness adapters

- **Hermes:** install the shared Agent Skill and connect the local MCP server or use the CLI.
- **Claude Code:** install the same Agent Skill under `.claude/skills/` and connect the local stdio MCP server through project-scoped `.mcp.json`.
- **Claude.ai:** use project instructions plus an approved connector or remote MCP service for live data.
- **ChatGPT:** use project instructions for behavior and an authenticated remote MCP Plugin for live systems. Uploaded project files alone are not a live email/database connection.
- **Other harnesses:** implement the five-tool adapter contract or call the CLI.

See `docs/INSTALL.md` and `docs/PLATFORM-MATRIX.md`.

Before connecting live data, read `docs/SOURCE-ADAPTER-GUIDE.md` and `docs/THREAT-MODEL.md`. A production installation requires a dedicated restricted harness profile, read-only source credentials, field-level authority rules, and no generic tool that bypasses the policy core.

## Safety invariants

- Never silently select the first business.
- Suppress draft and attachment proposals when the adapter's versioned freshness attestation is false.
- Never call something missing without an open task or task-backed current-document gap.
- Preserve communication/dashboard contradictions and suppress only the affected request.
- Require one exact recipient before drafting external copy.
- Reject sensitive, opted-out, suppressed, or do-not-contact recipient roles.
- Propose only attachment IDs explicitly named by open work.
- Exclude stale, path-escaping, sensitive, or unapproved files.
- Never return raw message subject, sender, body, content digest, attachment path, or attachment bytes.
- Never send, create a provider draft, or write a business record in the starter.

## Repository map

- `src/business_ops_agent/`: policy core, JSON adapter, approval semantics, CLI, optional MCP server
- `demo/`: zero-install static walkthrough and generated synthetic payload
- `skillsets/`: shared Agent Skill
- `adapters/`: harness-specific packaging guidance
- `examples/synthetic/`: public-safe demonstration evidence
- `templates/`: owner configuration, process, and permission templates
- `tests/`: contract, privacy, contradiction, and zero-side-effect tests
- `docs/`: contract, architecture, source-adapter guide, threat model, installation, and publication drafts
- `.github/`: read-only CI, manual demo-only Pages deployment, and public issue/PR intake

## Contributing and security

See `CONTRIBUTING.md` for the local quality gate and public-data rules. Report
suspected vulnerabilities privately using the process in `SECURITY.md`; never
put credentials or real business data in a public issue.

## Status

Version `0.1.0` is the initial public source release. The repository and static
demo contain synthetic data only. Live connectors, hosted services, provider
drafts, source writes, PyPI publication, and announcements remain outside this
release.

## License

Licensed under the [Apache License 2.0](LICENSE).