Papercuts

We want to make Minima the best CMS for humans and agents. So we’ve added an experimental feature: papercuts.

A papercut is friction with Minima itself — something that surprised you, took longer than it should have, or made you stop and work around it. Report one and it goes straight to the people who can fix it.

This command exists for agents. If you are an agent working through the CLI or the API, you are the one who hits these and the only one who can report them while the detail is still to hand. File it as it happens rather than saving it up, and carry on with the task — reporting is one call and nothing waits on it.

The alpha has no telemetry, so nothing reaches us unless it is sent.

What belongs here

• An error that said what went wrong but not what to do about it.
• A gap or a wrong statement in these docs.
• Three calls where one should have done.
• A flag or field name that meant something other than what you assumed.
• Help text that did not carry the thing you needed to know.

What does not belong here: bugs in your own code, questions you can answer by reading, and anything you have not actually hit yet.

Check before filing

minima papercut list

A papercut already answered fixed says the workaround you are about to write is unnecessary. One already open says the report is on record, and filing it again adds nothing.

Filing one

minima papercut report "entity-types properties add needed the type ID, not the key"

--message is the same thing as a flag, which is easier to build from a script:

minima papercut report \
  --message "push --apply printed the failure count but not the response body" \
  --harness claude-code \
  --model claude-opus-5

Identify yourself with --harness and --model when you can. A pattern across one harness is a different problem from a pattern across all of them, and only the report can say which this is.

The CLI builds the rest of the context itself — its own version, the Node version, and the platform. That is why reporting goes through this command rather than the raw API operation: the envelope that makes a report actionable is exactly the part a caller would have to hand-assemble and get wrong.

A message can run to 10,000 characters. Use them if the detail earns it.

Write it so it can be acted on

Name what you did, what you expected, and what happened. A papercut that only says something was confusing cannot be fixed, because nobody can tell which part was.

# Not actionable.
minima papercut report "properties are confusing"

# Actionable.
minima papercut report "entity-types properties add takes the type ID, but
entity-types list shows keys and the help says 'entity type' for both, so I
sent the key and got a 404 with no hint that the ID was wanted."

Reading them back

minima papercut list --order-by status
minima papercut get <papercutId>

list gives the message, the status, and the response, and takes the usual window and sort. get adds the client context the papercut was filed with.

response is null until a maintainer writes one.

Who can see them

A papercut is filed by the API key that reports it, against that key’s organization. Every key in the organization can read every papercut it has filed — this is not an anonymous channel, and the key itself is never shown back, since it identifies a credential rather than a person.

papercut list and papercut get are beta, so their shape may change.