---
description: Write or revise one durable fact in Grounded
argument-hint: <the rule, in one line>
allowed-tools: Bash(curl:*), Bash(jq:*)
---
Record this as a Grounded fact: $ARGUMENTS

Grounded answers over HTTP at `$GROUNDED_URL` (default `http://127.0.0.1:7437`). If `GROUNDED_TOKEN` is set, the API wants `Authorization: Bearer $GROUNDED_TOKEN`; with no token configured the header is ignored.

A fact is one terse, imperative line an agent must see before work starts. No rationale, no history. Write one only because the user stated or confirmed it, never by inference. If it explains how to use something, it is a pointer: name the doc instead of summarising it.

1. Check for an existing fact on the same subject, so you revise it instead of adding a near-duplicate:

```bash
jq -n --arg q '<subject>' '{query: $q, limit: 5, sources: ["fact"]}' |
  curl -s -X POST "${GROUNDED_URL:-http://127.0.0.1:7437}/recall" \
    -H 'content-type: application/json' \
    -H "authorization: Bearer ${GROUNDED_TOKEN:-}" \
    --data-binary @-
```

2. Write it. `scope` is `global`, `project:<name>` or `agent:<name>`. `topicKey` is a short stable kebab-case key: writing the same `(scope, topicKey)` again edits that fact in place.

```bash
jq -n --arg f '<one-line fact>' --arg s 'global' --arg k '<topic-key>' \
  '{fact: $f, scope: $s, topicKey: $k}' |
  curl -s -X POST "${GROUNDED_URL:-http://127.0.0.1:7437}/facts" \
    -H 'content-type: application/json' \
    -H "authorization: Bearer ${GROUNDED_TOKEN:-}" \
    --data-binary @-
```

Optional fields: `detail` (a short qualifier), `category`, `pinned` (true guarantees delivery: use sparingly), `importance` (0..1).

3. Read the reply. `delivery.delivered: false` means the fact will not be in the startup brief; `delivery.warning` means it is longer than its share. A 400 names the cap and how much to trim. To change one field of an existing fact, `PATCH /facts/<id>` with only that field.

Report the fact's `typedId` and whether it was delivered. If a call fails, read `GET /llms.txt` on the same base URL.