# 🤖 PLAN — why CONTRA is shaped this way, and what lands when

`PROTOCOL.md` is the spec. This is the reasoning and the order.

## Why build this at all

1Password is genuinely disappointing people. The complaints are not about
cryptography — they are about a product that grew away from the thing it
was for. That leaves an audience who already believe in password managers,
already pay for one, and are actively looking. They arrive with an export
file and a grievance, which is the easiest migration in software.

The second reason is that the family needs it. The CARLOS apps keep
reaching for a password manager as the place recovery credentials live —
and every one of those references is a dependency on a product none of us
control. A family password manager closes that loop.

## The position

Everything else in the category competes on features. CONTRA competes on a
sentence that its competitors structurally cannot say: **the operator sees
nothing at all** — not your vault, not your item names, not your email
address, not how many vaults you have.

That sentence is only worth saying if it survives audit, which is why the
class is A1 strict and why the greps are merciless. The moment we need an
"except…" clause, we are an A2 app competing on features again.

## Build order, and why this order

**1 — Instance + client-shape web console.**
The crypto and the storage contract get proven exactly once, in the place
where they can be iterated fastest and reviewed on a canary the same day.
This surface is client-shape by force: sealing must happen where the keys
are, so a server-rendered vault is not a thing that can exist. Marketing
and settings pages stay server-shape beside it.

Done when: signup, passphrase sign-in, recovery-code print, a working
vault, and the merciless greps green.

**2 — Native Mac app.**
Fully native, and deliberately *second*. A second client written against a
settled contract is a port; a second client written against a moving
contract is two half-designs. Everything the Mac app needs from the server
already exists by then.

**3 — AutoFill Credential Provider extension (macOS).**
This is where the product stops being a website. It is also where
distribution gets decided early rather than late: an
`ASCredentialProviderExtension` means a paid Apple developer account, code
signing, notarization, and a Sparkle-versus-App-Store call. That decision
constrains the Mac app, so it gets made at slice 2, not slice 3.

**4 — iOS.**
Same contract, third implementation, plus its own AutoFill extension.

## Import

1PUX first, client-side, because that is where the users are coming from
and because an unsealed export touching the server would break the one
rule on day one.

Bitwarden and Apple Passwords are wanted and deferred to discussions on
this repo. Passkeys need a documented manual path: 1Password will not
export them, so no importer can ever bring them across, and the honest
move is to tell the user exactly which ones need re-creating rather than
silently dropping them.

## Money

A real free rung, then **€5/year**.

Deliberately cheap, for a reason specific to this category: a password
manager somebody stops paying for is a password manager that loses their
data. Price it so lapsing is never the cheaper option. Shape follows
Slopbox — free rung that degrades generosity, never availability.

Metering from the first write; integer cents.

## Deferred, with triggers

The full list is in `AGENTS.md` under "Deliberately not built yet". The
two worth naming here:

- **Cross-instance sharing (federation).** Not in v1, and the family has
  already called this the biggest scope trap once. Single-instance sharing
  gets proven first.
- **Breach and reused-password monitoring.** Every implementation sends
  something derived from a password off the device. There may be an
  A1-compatible design; until somebody writes it down, it is not sketched.

## Open questions

- The recovery code's exact strength, alphabet and chunking — under review.
- Whether the daemon's `use` verb may make outbound requests itself or is
  limited to injecting into a subprocess environment — under review.
- Namespace: `contra` is taken on npm and as a GitHub org, and the good
  short domains are held. No password manager uses the name. See the
  namespace note in the branch discussion.