# Inteligir Comments

> Anchored comments in inteligir notes — body markers, the note's comment store, replies, resolution, and attribution.

- Skill: `kyh/inteligir-comments` (Agent Skill)
- Install (CLI): `npx skillmds@latest add kyh/inteligir-comments`
- Raw SKILL.md: https://api.skillmd.com/api/skills/kyh/inteligir-comments/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: kyh (https://skillmd.com/u/kyh)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/kyh/inteligir-comments

---


# inteligir Comments

A comment is a question, decision, or review point attached to exact evidence.
Ordinary wording and structure problems are not comments — fix those in the
text and move on.

A comment thread is two halves that must agree: **markers in the note's body**
and **an entry in the store**. One without the other is a broken thread.

## Body Markers

Wrap exactly the text the comment is about:

```markdown
The %%i:c1:start%%rollback path%%i:c1:end%% is unproven.
```

- Ids may hold letters, digits, `_`, and `-`. Pick one that appears nowhere else
  in the note or its store.
- Both edges are required and must carry the same ids.
- Several threads can share one range: `%%i:a,b:start%%text%%i:a,b:end%%`.
- Only root ids appear in the body. Replies live in the store alone.

Put markers **around** a whole inline pill or link, never inside one. To comment
on a block — an image, chart, canvas, HTML block, or fence — put each marker on
its own line above and below the block.

Markers inside a code fence are inert, like everything else in code.

## The Store

A note's comments live in `.inteligir/comments/<note-id>.json`, where
`<note-id>` is the note's frontmatter `id` (`inteligir comment add` mints one
into a note that has none). It is a JSON object keyed by comment id. A
`<note>.md.comments.json` beside a note is the older spelling: the server folds
it into the store the first time the note's comments are read, so never write
one.

| Field        | Required    | Contract                                            |
| ------------ | ----------- | --------------------------------------------------- |
| `text`       | yes         | The comment or reply                                |
| `createdAt`  | yes         | Unix seconds; never changes after creation          |
| `updatedAt`  | yes         | Unix seconds; bump whenever the entry changes       |
| `source`     | new entries | `user`, `agent`, or `external`                      |
| `parentId`   | replies     | An existing id in this file; no cycles, no dangling |
| `imageUrls`  | no          | Vault-relative paths under `assets/`                |
| `resolvedAt` | resolved    | Unix seconds                                        |
| `resolvedBy` | when known  | `user`, `agent`, or `external`                      |

```json
{
  "c1": {
    "text": "Is the rollback rehearsed, or only written down?",
    "createdAt": 1787788800,
    "updatedAt": 1787788800,
    "source": "user"
  },
  "c1-r1": {
    "text": "Rehearsed on staging; the note now says so.",
    "createdAt": 1787792400,
    "updatedAt": 1787792400,
    "source": "external",
    "parentId": "c1"
  }
}
```

Unknown fields are preserved — do not strip a key you do not recognize.

## Attribution

| Who wrote it                                  | `source` / `resolvedBy` |
| --------------------------------------------- | ----------------------- |
| A person in the app                           | `user`                  |
| The app's own agent                           | `agent`                 |
| A coding agent or tool editing files directly | `external`              |

If you are an agent, you are `agent` or `external` — never `user`. Missing
attribution on an old entry means unknown; leave it that way rather than
guessing.

## Replies, Resolving, Deleting

- A root has no `parentId`. A reply points at the root or another reply, and
  every reply must chain back to a root that has markers in the body.
- Answer what you can answer. Leave genuinely open questions open.
- Resolving a thread sets `resolvedAt` and `resolvedBy` on the root **and every
  descendant**, and bumps each `updatedAt`. **Keep the markers and the entries** —
  resolution is history, not deletion.
- Deleting is a person's decision. It removes the root's markers and every entry
  in the thread together.

## Before You Finish

- Every marked root has exactly one store entry, and every root entry has
  markers.
- Reply chains reach a marked root with no cycles.
- `source` matches who actually wrote it.
- Timestamps are Unix seconds; attachment paths are vault-relative.
- Resolved threads kept their markers and their text.