docs: add a compatibility policy and name removal releases

[pmoust]

Summary

Nothing said what a version number promised. Which surfaces were covered, how
long a deprecated spelling survived, and what a patch release could change were
all answered by whatever the last commit did, and three deprecation messages in
the tool said a thing "goes in the next release" without naming one.

docs/compatibility.md states it, short enough to stay true. Every public
surface is classified from the source as covered or explicitly not covered, the
deprecation window is two releases with removal in the third, and breaking
changes are recorded where the changelog is generated from. The brigd line
protocol, the JSON output and the human-readable text are declared unstable on
purpose, which is the more useful half of the page.

The three "next release" messages now name v0.1.0-rc17, with tests asserting
the release name so a later edit cannot slide back to "next".

Related issues

Closes #60
Refs #23, #20

Changes

• docs/compatibility.md, linked once from the README's Documentation list.
• BRIG_CREDENTIALS_CMD and hostCredential: warnings, and the help-text line,
  name v0.1.0-rc17 instead of "next release". cmd/brig/deprecated_test.go
  and internal/wrap/config_test.go assert it.

Two things to know before merging

BRIG_CREDENTIALS_CMD is being removed in #23, in flight now. If that lands in
rc17 the message is exactly right; if it slips, the policy's own rule is what
decides the number, not this text.

The policy says the support matrix lives in the README's platform sections. #20
is putting it in docs/support.md; whichever merges second fixes the pointer.

Checklist

• make all passes (vet, test, build)
• script/smoke.sh passes
• I have added or updated tests covering the change
• I have run go test ./... -race, if the change touches concurrency, subprocesses or the daemon
• I have exercised the change against a real runtime (brig run <agent>), if it touches the run, exec or credential path
• I have updated the affected docs (README, docs/security.md, docs/profiles.md, docs/brigd.md)

Credentials and the sandbox boundary

Message text only. No behaviour changes on either promise.

[ananos]

Worth having -- naming the removal release in the notice, and making that named release the authority, is the part that turns a deprecation into a promise someone can plan against.

Two bits have gone stale while it sat in draft, inline.

[ananos]

v0.1.0-rc17 shipped on 28 Aug, so the count is out of date. Perhaps say "every version to date is a release candidate" without the number -- then it cannot go stale again between drafting and merging.

[ananos]

This names v0.1.0-rc17 as the release that removes hostCredential:, and rc17 has already shipped -- the field is still in internal/profile (it has left the shipped profiles, which is the other half). So the page would land stating a deadline that has passed.

Either remove the field and keep the promise, or move the removal to the next release and say so here. The first is truer to the policy this page is introducing; the second is fine too, as long as the notice in main.go moves with it. The test pins the string, so it will keep passing either way -- which is why it is worth catching by eye now.

[ananos]

Still worth having -- naming the removal release and making it the authority is the part that turns a deprecation into something someone can plan against.

The difficulty is that this branch is 30 commits behind main and has been open since 4 September, and this is the one page where being behind is worse than being absent. Every other doc that goes stale is merely wrong; a compatibility page that goes stale promises coverage for surfaces that are not there and omits the ones that are, and a reader has no way to tell. Most of what follows is not a flaw in the writing -- it is main having moved under it.

I checked each of these against the current tree rather than reading, and inlined them. Nothing here needs re-thinking, but the page wants a pass over its lists before it comes out of draft.

The underlying tension is worth a thought too: four of the six are hand-kept lists that duplicate something the binary already knows, which is the same drift #145 is about for verbs and flags. Where a list can be derived -- the verbs and the run-line flags both come off brigFlags and the dispatch table -- deriving it in a test would keep this page honest the way 6ed914b just did for the completion test.

[ananos]

There are 13 v0.1.0-rc tags now, not twelve. This is the second time this number has gone stale on this branch -- it was eleven when I first read it.

So I would drop the count rather than correct it: "every version to date is a release candidate, and nothing without the -rc has shipped" says the same thing and cannot rot. The number adds no information a reader needs, and it is the one sentence on the page guaranteed to be wrong again by the next release.

[ananos]

This list and brig's actual verbs have diverged a long way. Asked the binary built from current main:

agent completion doctor info ls policy rm run secret sh stop telemetry version

So the page covers create, exec, shell, reset, env, help and profiles, and does not mention agent, completion, doctor, info, policy, telemetry or sh. Some of that is renaming (shell to sh, env deprecated toward info), but doctor, policy, telemetry and completion are simply newer than the branch.

That matters more here than on an ordinary page: a promise that names the covered verbs, and omits half of them, tells a script author their brig policy usage is uncovered when it is not.

[ananos]

Same drift, and this one closes the set explicitly -- "the set brig owns is the set here and no more" -- which makes an omission a wrong promise rather than an incomplete one.

What the run line actually offers today:

--cpus --detach --home --image --json --mem --network --no-project --offline --skills

Against the seven here: --name, --workspace and --memory are not among them, and --home, --json, --network, --no-project, --offline and --mem are missing from the page. --network is the one I would least want left out, since it is the flag that selects an isolation posture.

This is the list I would most like to see derived rather than typed: the rows are already in brigFlags with a position each, so a test could assert the page names exactly the posRun set.

[ananos]

This says a specific non-zero number is not a contract. README now says the opposite, under "Exit codes" at line 222:

brig returns a small, stable set of exit codes so a script can tell what went [wrong]

followed by a table giving each of 0-6 its own meaning. And #154 is building on that: internal/exitcode produces the same six for brigd, so brigd's clients will branch on them too.

Of the two, README's is the promise that is actually being kept, so I would bring this into line with it rather than the other way round -- otherwise the compatibility page is the more conservative of two documents that disagree, which is the confusing direction.

The sentence above it needs the same exception docs/security.md just gained on main: brig no longer always replaces itself with the runtime -- under --json it stays as the agent's parent to print one status line. The exit status is still the agent's own, so the promise holds; the mechanism described does not.

[ananos]

No longer macOS-only: #153 merged this morning, so brig secret also stores into a freedesktop Secret Service keyring on Linux (internal/secret/secretservice_linux.go), one item per secret in the default collection under the same sh.brig.secret service attribute.

Since this bullet is about the filesystem layout a user can depend on, it is worth saying both, and that the service name is the same on each.