clover's git

the-knife

1	# Assistant citations
2
3	Citations carry the selected excerpt and source identity in ordinary message text.
4	Drafts, clipboard copies, stashes, and sent messages keep that representation
5	without a separate citation store. The saved quote remains usable when its source
6	disappears or changes. The [shared format](../../packages/shared/src/assistantCitations.ts) uses
7	stable environment IDs without a browser origin, so moving between local, remote,
8	and tunnel connections does not change a citation's identity.
9
10	Source navigation is best effort. [Text selectors](../../apps/web/src/lib/assistantTextSelection.ts)
11	refer to rendered text after whitespace normalization, measured in UTF-16 units.
12	They cannot be applied to raw Markdown. The original excerpt keeps its whitespace;
13	normalization is only for locating it. Repeated text needs an unambiguous context
14	match, even if one occurrence still sits at the saved offsets. Guessing could
15	highlight the wrong claim.
16
17	Navigation owns the highlight's lifetime across virtual-row remounts. The source
18	row must be fetched, unfolded, mounted, and measured before quote positioning
19	takes over from normal timeline scrolling. Remounting must not revive a dismissed
20	highlight. The [navigation hash](../../apps/web/src/lib/assistantCitationNavigation.ts)
21	uses base64url because router normalization otherwise decodes whitespace and
22	source IDs inside the citation URI.
23
24	Expand citations with the [shared formatter](../../packages/shared/src/assistantCitations.ts)
25	before dispatch to a provider adapter. Send the saved excerpt without looking up
26	the source, distinguish quoted reference material from the user's comment, and
27	leave persisted messages in their original form. Input limits apply after
28	expansion as well as before it. A draft that fits as encoded links can exceed the
29	provider limit once expanded.