# Remogram public beta

Remogram **0.2.0-beta.1+** is the current beta line. This guide covers install, trust boundaries, and adoption for external agents.

## Install

```bash
npm install -g @remogram/cli@beta @remogram/mcp@beta
remogram --version
remogram doctor --json
```

Copy [`.remogram.json.example`](../.remogram.json.example) to your repo root and set `provider`, `owner`, `repo`, `baseUrl` (Gitea) or rely on `origin` remote parsing (GitHub/GitLab).

## Provider tiers

| Tier | Provider | Reads / plan | Writes (opt-in) |
|------|----------|--------------|-----------------|
| **A** | `gitea-api` | Full v1 surface | `cr_open`, `issue_open`, `issue_close`, `issue_comment`, `cr_edit`, `merge`, `status_set`, `publish_branch` |
| **B** | `github-api`, `gitlab-api` | Full v1 reads | `cr_open`, `issue_open`, `issue_close`, `issue_comment`, `cr_edit`, `merge`, `status_set`, `publish_branch` (GitHub/GitLab Tier B since 0.2.0-beta.1; #634, #693; `publish_branch`: git push via #705) |

Writes require **`write_commands`** in tracked `.remogram.json` and/or a local **operator overlay** (see below). Missing write id → `write_not_configured` (fail-closed).

## Operator write overlay

Do **not** store tokens in `.remogram.json`. Use:

```bash
export GITEA_TOKEN=...   # or GITHUB_TOKEN / GITLAB_TOKEN
export REMOGRAM_OPERATOR_CONFIG=~/.config/remogram/operator/gitea-api-owner-repo.json
```

See [`.remogram.operator.json.example`](../.remogram.operator.json.example).

## Fail-closed defaults

- Default **8 KiB** forge ingest cap (`REMOGRAM_FORGE_INGEST_MAX_BYTES` override is bounded)
- List/read paths use **projection** to strip bulky forge fields before parse
- `merge plan` does **not** authorize merge; empty `blockers[]` is readiness only
- `doctor --json` is the bootstrap gate before trusting other packets

## MCP parity

MCP tools mirror CLI write ids when configured. Run:

```bash
remogram contract --command export --json
```

Compare with MCP `list_tools` in your host. Composed reads: `observer_snapshot`, `semantic_diff`, `write_preview`, bundles.

## Smoke / contract verification

- Fixture repos: [remogram-smoke](https://gitlab.com/attebury/remogram-smoke)
- Local proof: `npm test` in the monorepo (1400+ tests at 0.2.0-beta.1)

## Release channel

- **npm tag:** `@beta` (not `latest`)