report_friction
Submit feedback when Hivelore tooling fails, misleads, or lacks clarity — bugs, suggestions, and docs issues are logged locally for maintainer review.
Instructions
Tell Hivelore's maintainer that HIVELORE ITSELF got in your way — a bug in a Hivelore tool, a misleading message, wrong docs, or an improvement idea.
USE THIS WHEN the friction is with Hivelore, not with the project you are working on:
a Hivelore tool or command errored, or did something other than what it documented
a message or return value misled you into a wrong action
the docs/description for a tool were wrong, missing, or contradictory
you can see a concrete improvement to how a Hivelore tool behaves
DO NOT USE for anything about the project's own code → that is mem_tried (a failed approach) or mem_save (a gotcha/convention). This tool is only for feedback ON THE TOOLING.
STAYS LOCAL. Nothing is published: the report is appended to a machine-local journal under
.ai/.runtime/ and a human reviews it with hivelore report list before anything reaches a
public tracker. Never put secrets or customer code in a report.
EVIDENCE BAR: kind='bug' REQUIRES a runnable repro. Without one the report is still kept,
but filed as 'suggestion' — an unreproducible bug claim cannot be acted on.
DEDUPLICATED: reports are fingerprinted on kind+surface+summary. If you get back already_reported=true, the point is already made — do not rephrase and send it again. The occurrence count is what ranks it for the maintainer.
PARAMETERS: kind — bug | suggestion | docs | confusing surface — the Hivelore tool or command involved (e.g. 'mem_save', 'enforce check') summary — one specific line stating the problem (this is the dedup key) expected — what you expected Hivelore to do observed — what it actually did (exact message or output) repro — a command/tool call that reproduces it, runnable as-is (required for 'bug')
RETURNS: { ok, kind, fingerprint, occurrences, already_reported, notice? }
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| kind | Yes | 'bug' = Hivelore did the wrong thing (REQUIRES `repro`; without one it is filed as a suggestion); 'suggestion' = an improvement idea; 'docs' = the documentation was wrong or missing; 'confusing' = it worked but the output/naming misled you. | |
| repro | No | The command or tool call that reproduces it, runnable as-is. Required to file a 'bug'. | |
| summary | Yes | One line stating the problem, as specifically as you can. This is the dedup key. | |
| surface | Yes | The Hivelore surface involved — an MCP tool or CLI command, e.g. 'mem_save', 'enforce check', 'sensors propose'. Used to group reports, so name the tool, not the file. | |
| expected | No | What you expected Hivelore to do. | |
| observed | No | What it actually did — the exact message or output. |