# Build on Repowise

The surfaces a tool, service or agent can build on, how each one authenticates, and which contracts are versioned and stable across releases.

Repowise exposes the same index through several surfaces. Pick the one that matches
what you are building, then rely on the contracts marked stable below.

## Pick a surface

| You are building | Use | Start here |
|---|---|---|
| An AI agent or an agent tool | The MCP server: ten task-shaped tools over stdio or streamable HTTP | [MCP tools](https://docs.repowise.dev/mcp/overview) |
| A web app, bot or service | The REST API served by `repowise serve` | [REST API](https://docs.repowise.dev/build-on-repowise#rest-api) |
| A script or a CI step | The CLI with `--format json` (or `sarif`, `junit`, `csv` where offered) | [CLI](https://docs.repowise.dev/cli/overview) |
| A Python service reviewing changes, with or without a checkout | `ChangeReviewService` from `repowise.core` | [Python change review](https://docs.repowise.dev/build-on-repowise#python-change-review) |
| An alert, a digest or a SIEM feed | Component events as CloudEvents 1.0.2 | [Events](https://docs.repowise.dev/build-on-repowise#events) |
| A report, an audit pack or a dashboard of your own | Report and Change Record JSON | [Versioned contracts](https://docs.repowise.dev/build-on-repowise#versioned-contracts) |
| A new data source, identity provider or output | A plugin on a named seam | [Plugins and seams](https://docs.repowise.dev/build-on-repowise#plugins-and-seams) |

## REST API

`repowise serve` publishes its own reference: `/openapi.json`, Swagger UI at `/docs`
and ReDoc at `/redoc`, on `http://127.0.0.1:7337` by default.

Each GitHub release carries the same document as an asset, so you can fetch the spec
for the version you run without starting a server:

```bash
curl -L -o openapi.json \
  https://github.com/repowise-dev/repowise/releases/latest/download/openapi.json
```

Every operation in the release asset carries `x-repowise-stability`:

| Value | Meaning |
|---|---|
| `stable` | An integration route. A breaking change to it is named in the changelog. |
| `internal` | A payload shaped for the bundled dashboard. It can change in any release; do not build on it. |

Things the schema cannot state, such as which routes make model calls, error shapes,
the two SSE streams and shared conventions, are in the
[REST API notes](https://github.com/repowise-dev/repowise/blob/main/docs/reference/API_REFERENCE.md).

## Authentication

| Setup | Who can call |
|---|---|
| No `REPOWISE_API_KEY`, server on `127.0.0.1` | Local callers only. A request from the network gets `403`. |
| `REPOWISE_API_KEY` set | Callers sending `Authorization: Bearer <key>` |
| Scoped tokens in `~/.repowise/tokens.yaml` | Callers with a token, limited to the repositories and MCP tools it lists, until `expires_at` |

Tokens are stored as SHA-256 hashes. The same check guards REST, the MCP streamable
HTTP and SSE transports, and chat, which runs only the tools in the caller's scope.
MCP over HTTP serves an RFC 9728 protected-resource document; set
`REPOWISE_PUBLIC_URL` behind a proxy. Webhooks verify their own signatures. Details:
[environment variables](https://docs.repowise.dev/installation/env-vars) and [security](https://docs.repowise.dev/security).

```yaml
# ~/.repowise/tokens.yaml
tokens:
  - id: ci-bot
    sha256: 9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08  # hex SHA-256 of the token
    repos: [payments-api]
    tools: [get_change_risk, get_risk]
    expires_at: 2027-01-31T00:00:00Z
```

## Python change review

`repowise.core` is importable on its own, with no server and no database session. A
bot or CI job can review a change in one call, from a checkout or from bytes:

```python
from repowise.core.analysis.change_review import ChangeReviewRequest, ChangeReviewService
from repowise.core.analysis.change_health import GitRevisionSource

service = ChangeReviewService(GitRevisionSource("."), repo_path=".")
bundle = service.review(ChangeReviewRequest(revspec="HEAD"))
print(bundle.directive.status, bundle.directive.headline)
```

Full reference:
[CHANGE_REVIEW_API.md](https://github.com/repowise-dev/repowise/blob/main/docs/reference/CHANGE_REVIEW_API.md).

## Events

Each `repowise init` and `update` snapshots every component and stores what moved as a
typed event: ownership shift, owner inactive, bus factor drop, new hotspot, contract
added or broken, decision stale, dead-code growth, test reach drop.

```bash
repowise events --since 7d --format jsonl     # CloudEvents 1.0.2, one per line
curl -H "Authorization: Bearer $KEY" \
  http://127.0.0.1:7337/api/repos/$REPO_ID/events
```

Events are also appended to `.repowise/events.jsonl`, and the `event-sink` seam
delivers them anywhere else.

## Versioned contracts

These shapes carry a version number and change only with a version bump:

| Contract | Version field | Where you get it |
|---|---|---|
| Change Record | `schema_version` | `repowise changes show --format json`, `GET /api/repos/{id}/changes/{change_id}` |
| Change Record as in-toto | in-toto Statement v1 | `repowise changes show --format in-toto` |
| Change evidence checklist | `schema_version` | `repowise changes show`, `get_change_risk(include=["evidence"])` |
| Evidence reports | `schema_version` | `repowise report assessment --format json`, and the same for `changes` and `inventory` |
| Evidence cards | `schema_version` | Chat turns and the `@repowise-dev/types` package |
| Events | CloudEvents `specversion` 1.0.2 | `repowise events`, `GET /api/repos/{id}/events` |
| Package usage | CycloneDX 1.6 | `repowise packages export --format cyclonedx` |
| Policy results | SARIF 2.1.0, JUnit XML | `repowise check --sarif-file`, `--junit-file` |
| MCP responses | The `_meta` envelope | Every MCP tool ([response fields](https://docs.repowise.dev/mcp/overview)) |

## Plugins and seams

An installed Python package extends Repowise through the `repowise.plugins` entry
point, or through `REPOWISE_PLUGINS=module:attr` for a quick local test. The
[plugin author guide](https://github.com/repowise-dev/repowise/blob/main/docs/reference/PLUGINS.md)
walks through a first plugin, catalogs every registry and seam (when it runs and
what a failure does), covers testing and publishing, and lists community
plugins such as a MarkItDown PDF extractor; the
[hello example](https://github.com/repowise-dev/repowise/tree/main/examples/plugins/hello)
is an installable plugin that adds a CLI command, an MCP tool, an event sink and a
report section.

Registries take additions alongside the built-ins: `cli-command`, `mcp-tool`,
`pipeline-hook`, `llm-provider` and `embedder`. A provider or embedder a plugin
registers is found by name like a built-in one. Each seam is a named extension
point with a local default:

| Seam | Default | What a plugin can supply |
|---|---|---|
| `authenticator`, `authorizer` | Shared key and scoped tokens | Your identity provider and access rules. An authorizer receives each repo by its id, name and workspace alias, and the `claims` your authenticator put on the principal; one whose methods accept `action` is also told `READ` or `WRITE` on every call |
| `document-extractors` | None | Markdown from a file type Repowise does not otherwise process (a slide deck, a diagram), indexed under the original path. Each extractor may set `max_source_bytes`, up to a 100 MiB ceiling |
| `index-persistence` | None | Your own records written inside each index write's transaction, and published after it commits |
| `team-directory` | CODEOWNERS and `.repowise/teams.yaml` | A directory or SCIM source |
| `change-metadata` | Git trailers and closing keywords | Reviewers, approvals and links from your forge |
| `event-sink` | `.repowise/events.jsonl`, stdout | Chat, email, webhooks or a SIEM |
| `advisory-source` | A file you supply | An advisory feed |
| `report-section`, `report-renderer` | Built-in sections, JSON, Markdown, HTML, CSV | Your own sections and formats |
| `suspect-signal` | Five built-in signals | Another ranking signal |
| `chat-tools`, `chat-dataset`, `chat-view` | Built-in tools, datasets and views | Your own chat tools and charts |

```toml
# pyproject.toml of your plugin package
[project.entry-points."repowise.plugins"]
acme = "acme_repowise:register"
```

```python
# acme_repowise/__init__.py
def register() -> None:
    from repowise.core.registry.plugins import SeamRegistry

    SeamRegistry("event-sink").register("acme", AcmeSink(), default=True)
```

`repowise plugins` (or `--format json`) lists what loaded, what failed, every
registration each plugin made as `kind:name`, and every seam with the
implementation it uses. `SeamRegistry.all()` returns every implementation in
registration order, and `REPOWISE_SEAM_<NAME>` picks one by name. A plugin can add
CLI commands but never replaces a built-in one, and a repository's `.repowise/.env`
cannot select plugins.

### Storage revisions

A plugin that keeps its own tables (such as the records an `index-persistence`
implementation writes) registers a revision for each change to them with
`storage_migrations.register(StorageMigration(namespace, revision, checksum, apply))`
from `repowise.core.registry.storage_migrations`. Registering touches no
database.

- Opening an index applies each unapplied revision after the core schema, each
  in its own transaction under the writer lock, and records it in
  `plugin_storage_revisions`, outside the core migrations. Revisions apply in
  the order a namespace registers them, and namespaces are independent.
- `apply` receives the async connection and leaves commit and rollback to
  Repowise.
- A changed checksum fails the open, so a change ships as a new revision.
- An index that cannot take the write still opens; the plugin reads `pending`
  in `repowise plugins` until a later open applies the revision, and its seam
  implementations wait until then.

`repowise plugins --format json` lists each plugin's storage revisions as
`applied` and `pending`. The
[plugin author guide](https://github.com/repowise-dev/repowise/blob/main/docs/reference/PLUGINS.md#storage-revisions)
has a worked example.

The plugin API is experimental. `PLUGIN_API_VERSION` (from
`repowise.core.registry`, and `api_version` in `repowise plugins --format json`)
is bumped on a breaking change to a registry or seam contract, and the change is
named in the changelog; check it in `register()` if a mismatch would break
silently.

## For coding agents

An agent building on Repowise needs three files:

- `https://docs.repowise.dev/llms.txt`: the index of these docs.
- `openapi.json` from the latest release: every REST route with its stability label.
- [MCP tools](https://docs.repowise.dev/mcp/overview): the tool surface and response fields.

Build on `stable` routes and versioned contracts only, and read `_meta` on every MCP
response to know which commit the answer came from.
