---
title: "Papercuts"
description: "How an agent reports friction with Minima itself, and reads back what a maintainer said."
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.minima.ltd/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

```sh
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

```sh
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:

```sh
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.

```sh
# 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

```sh
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](/developers/querying). `get` adds the client context the
papercut was filed with.

| Status | Meaning |
|---|---|
| `open` | Filed. No maintainer has responded yet. |
| `fixed` | Addressed. |
| `declined` | Read and not being changed; the response says why. |

`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.

Source: https://docs.minima.ltd/cli/papercuts/index.mdx