barako, a CLI that configures an instance from a file, so setup is reviewable and an agent can drive it

`barako`, a CLI that configures an instance. The immediate goal is that someone can say "using barako cli create a simple attendance system" to an agent and get a working one.

## Two reasons, and the second is the one that makes this non-optional

**Agent-drivable.** The admin UI is for a person clicking. An agent cannot click, but it can write a file and run a command, and everything a process owner configures (content types, fields, roles, permissions, lifecycles, workflows, connectors) is already expressible as data. An agent that knows the schema can turn a sentence into a working attendance system.

**Configuration as code.** This is the reason to build it even if no agent ever runs it. Today a barakoCMS setup lives in a database and nowhere else. There is no way to version it, review it in a pull request, promote it from staging to production, or stand up an identical instance. The honest answer to "how do I promote a config change" is currently "click the same things again and hope", which is the question every enterprise buyer asks and the one this project cannot yet answer.

The second reason also disciplines the first. A CLI built for promotion is declarative and idempotent, and that is exactly what makes it safe for an agent to drive.

## Declarative, not imperative

```
barako apply -f attendance.yaml # converge the instance to the file
barako plan -f attendance.yaml # what would change, without changing it
barako export > current.yaml # what is configured now
```

Not `barako create content-type ...` as the primary interface. Imperative commands cannot be re-run, cannot be diffed, and produce a different result depending on what was already there. An agent that half-finishes an imperative run leaves an instance nobody can reason about, and re-running it makes things worse rather than better.

`export` matters as much as `apply`: it is what lets someone configure by clicking, then capture the result, then review it. It is also the honest test of whether the model is complete, because anything `export` cannot represent is something the CLI cannot promote.

## What makes it usable by an agent, specifically

**A machine-readable description of what is valid.** An agent guessing field type names produces a plausible file that fails on apply. `FieldTypeRegistry` already knows the accepted set and `/api/meta` already exists, so this is exposure rather than invention.

**`--json` as a contract, not a convention.** Every command, every error, stable shape, documented. This is worth stating explicitly because the same promise was made loosely on another BaryoDev CLI and stayed a convention, which is worse than not offering it: an agent parses it and breaks silently when it drifts. It needs a test asserting the shape.

**`plan` before `apply`, and a human in between by default.** The output of `plan` is what a person reviews. An agent that can apply without a plan is an agent that can drop a content type at 2am.

**Errors that say what to do.** "Unknown field type 'currency', accepted types are money, decimal, ..." is actionable by an agent on the next attempt. "400 Bad Request" is not.

## Constraints

**Scoped credentials.** `ApiKeyScopes` already exists. The CLI uses an API key with the scopes the operation needs, not a SuperAdmin session. An agent holding platform-admin credentials is a bad default however careful the agent is.

**Destructive changes are refused by default.** Removing a field from a content type destroys data. `plan` names it, `apply` refuses it, and a separate explicit flag allows it. The failure this prevents is an agent tidying a config file and taking a column with it.

**It is a client, nothing more.** The API is already headless and complete. The CLI must not reach into the database or grow endpoints of its own, or it becomes a second way to do everything with its own bugs. This sits on the .NET client in `docs/2026-08-18-client-layer-design.md`, which is another reason that work matters.

**Config as code and the admin UI must agree.** Two sources of truth for the same setting is the precedence problem in BaryoDev/barakoCMS#343 again, at a larger scale. `export` after a click-configured change has to round-trip, and there needs to be a test that it does.

## What it does for the positioning

"Spins up easily" gets much stronger. It goes from "one compose file and then an afternoon of clicking" to "one compose file and one apply". It also makes examples real: an attendance system, an invoice approval flow and a leave request become files in a repository that anyone can apply and read, rather than screenshots.

## Done when

- `barako apply -f attendance.yaml` produces a working attendance system on a fresh instance, and running it twice changes nothing the second time.
- `barako export` on that instance produces a file that applies cleanly to another one, asserted by a test that does exactly that.
- `plan` shows a destructive change and `apply` refuses it without an explicit flag.
- Every command emits stable JSON, with a test pinning the shape.

Related: BaryoDev/barakoBrew#4 for the portal that end users then work in, BaryoDev/barakoCMS#339 for the scenario this makes reproducible, and `docs/2026-08-18-client-layer-design.md` for the client it stands on.