# Raveil Frontispice

**Frontispice** is a small, local-first **agent handoff core** with an optional Model Context Protocol (MCP) adapter. It lets one AI session leave **curated, explicit context** for another—especially ChatGPT → Codex—without copying an entire conversation history.

The name comes from Maurice Ravel's *Frontispice* (1918). In Raveil naming, Frontispice is the entry/boundary surface through which one agent leaves a concise handoff for another.

> Status: **0.1.0 / alpha**. The storage schema and authority boundary are intentionally small.

## Architecture in one sentence

**Frontispice Core owns handoff state; adapters expose it to hosts; agents decide what becomes repository truth.**

```text
                         ┌──────────────────────┐
 ChatGPT Web ── MCP ───▶ │                      │
                         │  Frontispice Core    │
 Future host ─ adapter ─▶│                      │
                         │  SQLite handoffs     │
                         │  project sequences   │
 Codex ─────── MCP ────▶ │  consumer cursors   │
                         │  routing/provenance  │
                         └──────────┬───────────┘
                                    │
                                    │ context only
                                    ▼
                              Librarian / agents
                                    │
                                    ▼
                           repository Markdown/code
```

MCP is deliberately **an adapter, not the product boundary**. The core has no dependency on ChatGPT, Codex, MCP, HTTP, Git, or shell execution.

See [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md).

## What problem it solves

```text
ChatGPT discussion
      │
      │ explicit: "send these conclusions to Codex"
      ▼
transport adapter
      │
      ▼
Frontispice Core / local SQLite inbox
      │
      │ next Codex start/resume
      ▼
Librarian checks consumer cursor
      │
      ├── architecture specialist
      ├── research specialist
      └── implementation specialist
      │
      ▼
validated repository Markdown / ADR / code
```

Frontispice is **not** a ChatGPT conversation scraper, Git agent, shell tool, browser, or autonomous background daemon. The sender chooses what to hand off. The receiver verifies it and decides what belongs in the repository.

## Core model

Each registered project gets a canonical lowercase kebab-case key and a monotonically
increasing `sequence`. Project names are resolved through the registry before handoffs are
accepted; agents must ask the user before registering an unknown project. Each consumer—for
example `librarian`, `architecture`, or `research`—has its own monotonic cursor.

One agent acknowledging sequence 42 therefore does **not** hide it from another. A resumed Codex session asks for messages newer than `librarian`'s last cursor.

## Components

```text
src/raveil_frontispice/
├── core/
│   ├── service.py       # transport-neutral public service
│   ├── store.py         # SQLite state + provenance
│   ├── security.py      # high-confidence secret guardrail
│   ├── validation.py
│   └── config.py
└── adapters/
    └── mcp.py           # optional MCP tool surface
```

The Python core can be installed and tested without the MCP SDK. The MCP dependency is an optional extra.

## Security by design

Frontispice deliberately avoids powerful capabilities:

- no shell execution
- no arbitrary filesystem or Git writes
- no URL fetching/application network calls in the core
- no delete MCP tool in v0.1
- owner-only database permissions where supported
- bounded inputs and parameterized SQLite queries
- high-confidence credential-pattern rejection by default
- explicit idempotency keys for safe publisher retries
- local HTTP adapter is loopback-only in v0.1
- handoff content is **untrusted data, not instructions**
- repository changes happen through the receiving agent's normal permission model, not Frontispice

Read [`SECURITY.md`](SECURITY.md) before deploying beyond a single trusted user/machine.

## Current ChatGPT surface limitations

As of **2026-08-09**, OpenAI's custom MCP / Developer mode flow is a **web** surface. It is not a way to attach a private custom MCP directly to the ChatGPT iPhone app. Published plugins are also currently documented for web/desktop/Codex rather than mobile.

This is why Frontispice treats MCP as one adapter. The core does not need to change when another supported host/transport becomes available.

For current setup options and exact limitations, see [`docs/INTEGRATION.md`](docs/INTEGRATION.md).

## Quick start: core only

```bash
git clone <your-raveil-frontispice-repository-url>
cd raveil-frontispice
python -m pip install -e .
frontispice doctor
```

Or with `uv`:

```bash
uv sync --extra dev
uv run frontispice doctor
```

## Quick start: MCP adapter + Codex

```bash
uv sync --extra mcp --extra dev
uv run frontispice serve
```

Connect Codex:

```bash
codex mcp add frontispice -- \
  uv --directory /ABSOLUTE/PATH/TO/raveil-frontispice \
  run --extra mcp frontispice serve

codex mcp list
```

For the complete ChatGPT-web + private MCP + Codex workflow, see [`docs/INTEGRATION.md`](docs/INTEGRATION.md).

To publish this repository safely to GitHub, see [`docs/PUBLISHING.md`](docs/PUBLISHING.md).

## MCP tools

The optional MCP adapter exposes:

- `frontispice_list_projects`
- `frontispice_register_project`
- `frontispice_publish_handoff`
- `frontispice_delivery_status`
- `frontispice_list_updates`
- `frontispice_read_handoff`
- `frontispice_route_handoff`
- `frontispice_mark_applied`
- `frontispice_advance_cursor`
- `frontispice_project_status`

The adapter is intentionally thin: validation, secret checks, storage, cursors, routing, and provenance live in Frontispice Core.
Route lookup remains available in Frontispice Core but is not exported as a separate MCP tool;
the ChatGPT-facing tool surface is intentionally capped at ten high-value operations.

Publish success is receipt-based. A successful call returns
`delivery_status="committed"` plus a receipt containing the handoff ID, canonical project,
sequence, content checksum, and commit timestamp. Natural-language claims without that receipt
must be treated as **not sent**. `frontispice_delivery_status` verifies a receipt later by
handoff ID or idempotency key and can additionally compare the checksum.

## Project selection UX

Project identity is registry-backed rather than free-form:

1. Codex registers its repository once, after explicit user confirmation.
2. ChatGPT resolves the requested project before publishing.
3. A single registered project can be selected automatically.
4. Multiple projects produce a structured selection prompt for the user.
5. Unknown projects produce a confirmation prompt and are never silently created.

Keys are normalized case-insensitively (`Raveil`, `RAVEIL`, and `raveil` resolve to
`raveil`; spaces and underscores become hyphens). Registering a canonical project merges
legacy case/spelling variants without changing handoff IDs. Because old sequence numbers can
collide, merged handoffs are resequenced by creation time and affected consumer cursors reset
to zero so no handoff is silently skipped.

## Bundled Codex librarian workflow

```text
templates/codex/
├── AGENTS.md.snippet
├── .codex/
│   └── config.toml.snippet
└── .agents/
    └── skills/
        └── frontispice-librarian/
            └── SKILL.md
```

The Librarian treats inbox material as untrusted context, classifies it, delegates verification where useful, integrates durable conclusions into canonical repository files, records provenance, and advances its cursor only after deliberate handling.

## Data location

Default:

```text
~/.frontispice/frontispice.sqlite3
```

Override:

```bash
export FRONTISPICE_DB=/secure/path/frontispice.sqlite3
```

Do not place the database in a public repository.

## Environment variables

| Variable | Default | Purpose |
|---|---:|---|
| `FRONTISPICE_DB` | `~/.frontispice/frontispice.sqlite3` | SQLite path |
| `FRONTISPICE_MAX_CONTENT_BYTES` | `262144` | Maximum handoff body size |
| `FRONTISPICE_ALLOW_SENSITIVE` | `false` | First half of deliberate secret-scan override |

A secret-scan override requires **both** `FRONTISPICE_ALLOW_SENSITIVE=true` and `allow_sensitive=true` on the publish call.

## Development

Core-only development:

```bash
python -m pip install -e '.[dev]'
ruff check .
pytest
```

Full adapter development:

```bash
python -m pip install -e '.[mcp,dev]'
ruff check .
pytest
```

## Design principles

1. **Core before transport** — MCP is an adapter, not Frontispice's identity.
2. **Curated, not copied** — never mirror whole conversations by default.
3. **Inbox, not truth** — receiving agents verify against repository reality.
4. **Data, not commands** — handoff bodies cannot confer authority.
5. **Least authority** — Frontispice stores handoffs; repository tools do repository work.
6. **Per-consumer cursors** — multi-agent readers do not steal each other's unread state.
7. **Traceability** — routing and applied provenance remain queryable.
8. **Local first** — no public listener is required for the local core.
9. **Surface-aware** — unsupported ChatGPT clients are documented, not worked around with unsafe public endpoints.

## License

Apache License 2.0. See [`LICENSE`](LICENSE).