Complete LSP citation authoring with ID completion

[vjovanov]

Closes #472

Before, grund-lsp offered no suggestions for a partially written citation. Now, in a Markdown note in this repository, request completion after either prefix, choose FS-lsp (“grund ships an optional LSP server”, docs/functional-spec/FS-lsp.md), and accept with the editor's normal binding:

See §FS-ls   →   See §FS-lsp
See $$F     →   See §FS-lsp

The server advertises and handles textDocument/completion. The new declared-ID contract is §FS-lsp.1.6; completion leaves the reserved list in §FS-lsp.1.5, and the shell specification points editor readers to this separate cached surface (§FS-completions).

• Recognition uses the edited document's effective marker, trigger and ID grammar, including member overrides, empty prefixes and longer prefixes. Completion respects formatter-protected contexts while allowing source comments and Python docstrings. Automatic trigger advertisement uses deduplicated final characters of initially loaded introducers; manual requests use current configuration, while newly introduced automatic trigger characters require a restart (§FS-lsp.1.6.1).
• Candidates stay in the document owner's catalog unless a complete known alias plus / selects a loaded target's catalog and grammar. Ambiguous declarations and incomplete discovery withhold edits. Items include titles and project-relative source paths; case-sensitive prefix matches sort by exact match, configured kind order and ID, with explicit sortText and filterText (§FS-lsp.1.6.2).
• Acceptance replaces the whole active token, including an old suffix beyond the cursor and any section suffix, with one plain-text canonical citation. UTF-16 ranges preserve non-BMP neighbors, adjacent citations, surrounding prose and Markdown destinations. The overlap correction keeps punctuation belonging to an ID from being mistaken for another marker or trigger, including hyphen and underscore configurations (§FS-lsp.1.6.3). The underscore scanner limitation below remains separate from these token/edit semantics.
• Candidates and effective configuration are built with the existing snapshot and notified overlays, without a per-request declaration scan. Declaration changes refresh candidates; closing an overlay restores disk state. After applying a completion or on-type edit, clients must discard competing obsolete responses, notify the document change and re-request (§FS-lsp.1.6.4).

Core owns recognition, candidate selection and byte edits; LSP owns capability advertisement, protocol items and UTF-16 conversion. The additive completion context and snapshot wrapper preserve existing public constructors (§AR-lsp.1, §AR-lsp.2). This adds no CLI/config migration, value-specific completion or editor extension. Ordinary declared-ID candidates remain the value behavior in §FS-lsp.4.2.

The shipped live transform retains its timing: trigger conversion waits for a recognized suffix, while numeric shorthand expansion waits for its token boundary (§FS-lsp.1.4.1). Its distinct expansion and eager-conversion exclusions remain intact (§FS-lsp.1.4.3, §FS-lsp.1.4.4); baseline investigation found no generic trigger defect requiring a rewrite.

The setup guide documents client-owned acceptance and response handling for VSCode, Neovim, Zed, Helix and Emacs, with optional mappings where needed. Helix cycles with Tab and accepts with Enter; the server does not intercept keys (§FS-lsp.2.3). This guidance was checked against official sources; interactive editor validation is not claimed. Optional README depth moved into linked user guides, preserving runnable examples and keeping the README at 250 nonblank lines. The final integration commit restores the rules-example link, inventories four additive core exports and replaces three timed-out Emacs manual links with corresponding reachable manual-source mirror links.

Verification

The specification and original 22 protocol acceptance cases were committed first in 697b51001f. Their baseline failures independently pin the absent completion provider and unsupported requests (-32601); those cases were preserved throughout implementation and both review/fix rounds. Added core and protocol coverage pins configured introducer/grammar overlap, whole-token and UTF-16 edits, neighbor preservation, owner/qualified isolation, protected contexts, overlays, and completion/on-type response sequences. Resolving default/hyphen-marker controls verify accepted-citation navigation and formatting/on-type replay; underscore-marker cases prove token/edit behavior only. Deterministic completion and acceptance parity are now explicit in §FS-lsp.4 and §FS-lsp.4.1.

At final commit 2c07c4762631d9aba379c1f02335c82c99dd300a, pre-commit run --all-files exited 0 in 7m02s. All ten hooks passed: Cargo formatting, warnings-as-errors workspace/all-targets build, workspace/all-targets tests with grund/test-workspace-load-count, Python tests, grounding, citation formatting, managed-block checking, links, file budgets and attribution checking. Focused rules-documentation, public-inventory and link retries also passed before the complete rerun. No gate bypass or budget exception was used. The grounding/formatting hooks run the checkout through cargo run; they do not use the older installed formatter discussed below. Hosted CI and merge are not yet established.

Adjacent limitations deliberately deferred

These findings predate this feature and remain with their separate tool reports:

• R2-03 / grund.57: the scanner's word boundary makes unqualified underscore-marked citations invisible to scanning, refs, cover and LSP navigation. Completion's underscore token/edit coverage does not establish resolving acceptance for that output.
• R2-04, carried R1-04 / grund.56: colon-format declarations appear in list but show cannot resolve them.
• R2-05 / grund.48: installed 0.15.1-dev can write wrong relative link destinations when formatting a bare file argument. Committed links were repaired, and fresh absolute-path formatting controls pass.

The author approved the unchanged planned proposal; it declared no prerequisites. #466 and #459 remain coordination concerns. Clarify and agora were cancelled as unnecessary. Both review/fix rounds ran, with all four review/fix steps escalated for incomplete delivery; green made one bounded documentation/integration fix before the passing complete rerun.

Held for human discussion. Membership in the 1.0 work and implementation order remain undecided; this is not a release commitment.

AI workflow: `rhei`, 20 agent invocations across 1 model; 11 tasks completed, 5 in progress.

1. github-issues-agent-grounds-grund-472-implement-076ca082.ticket supervising (visit 1) — cdx, openai/gpt-6.1-sol — 1m32s — 371.4k in / 3.8k out
2. github-issues-agent-grounds-grund-472-implement-076ca082.ticket.triage assessing — cdx, openai/gpt-6.1-sol — 9m57s — 2.7M in / 25.0k out
3. github-issues-agent-grounds-grund-472-implement-076ca082.ticket supervising (visit 2) — cdx, openai/gpt-6.1-sol — 2m28s — 768.0k in / 6.1k out
4. github-issues-agent-grounds-grund-472-implement-076ca082.ticket.plan planning — cdx, openai/gpt-6.1-sol — 5m37s — 2.0M in / 12.9k out
5. github-issues-agent-grounds-grund-472-implement-076ca082.ticket supervising (visit 3) — cdx, openai/gpt-6.1-sol — 1m21s — 430.8k in / 3.4k out
6. github-issues-agent-grounds-grund-472-implement-076ca082.ticket supervising (visit 4) — cdx, openai/gpt-6.1-sol — 1m36s — 439.0k in / 4.2k out
7. github-issues-agent-grounds-grund-472-implement-076ca082.ticket.specify specify — cdx, openai/gpt-6.1-sol — 15m27s — 6.1M in / 38.1k out
8. github-issues-agent-grounds-grund-472-implement-076ca082.ticket supervising (visit 5) — cdx, openai/gpt-6.1-sol — 1m57s — 502.5k in / 4.9k out
9. github-issues-agent-grounds-grund-472-implement-076ca082.ticket.implement implement — cdx, openai/gpt-6.1-sol — 24m02s — 8.3M in / 57.7k out
10. github-issues-agent-grounds-grund-472-implement-076ca082.ticket supervising (visit 6) — cdx, openai/gpt-6.1-sol — 3m05s — 989.5k in / 7.9k out
11. github-issues-agent-grounds-grund-472-implement-076ca082.ticket.review-1 review — cdx, openai/gpt-6.1-sol — 6m34s — 1.8M in / 16.1k out
12. github-issues-agent-grounds-grund-472-implement-076ca082.ticket supervising (visit 7) — cdx, openai/gpt-6.1-sol — 1m45s — 546.0k in / 4.5k out
13. github-issues-agent-grounds-grund-472-implement-076ca082.ticket.fix-1 fix — cdx, openai/gpt-6.1-sol — 11m06s — 3.1M in / 27.4k out
14. github-issues-agent-grounds-grund-472-implement-076ca082.ticket supervising (visit 8) — cdx, openai/gpt-6.1-sol — 1m51s — 551.9k in / 4.7k out
15. github-issues-agent-grounds-grund-472-implement-076ca082.ticket.review-2 review — cdx, openai/gpt-6.1-sol — 8m47s — 2.7M in / 22.6k out
16. github-issues-agent-grounds-grund-472-implement-076ca082.ticket supervising (visit 9) — cdx, openai/gpt-6.1-sol — 2m06s — 726.6k in / 5.4k out
17. github-issues-agent-grounds-grund-472-implement-076ca082.ticket.fix-2 fix — cdx, openai/gpt-6.1-sol — 6m08s — 1.4M in / 16.5k out
18. github-issues-agent-grounds-grund-472-implement-076ca082.ticket supervising (visit 10) — cdx, openai/gpt-6.1-sol — 1m49s — 608.1k in / 4.7k out
19. github-issues-agent-grounds-grund-472-implement-076ca082.ticket.green green-fix — cdx, openai/gpt-6.1-sol — 3m15s — 1.4M in / 7.4k out
20. github-issues-agent-grounds-grund-472-implement-076ca082.ticket supervising (visit 11) — cdx, openai/gpt-6.1-sol — 2m12s — 792.5k in / 5.6k out

Accounting	Value
cost	$10.57
total tokens	36.5M
input tokens (incl. cache)	36.2M
input cache read	34.0M
input cache write	-
output tokens (incl. cache)	278.8k
output cache read	-
output cache write	-
coverage	Complete