clickable citations: agent convention in AGENTS.md, decided and recorded#45
Draft
vjovanov wants to merge 3 commits into
Draft
clickable citations: agent convention in AGENTS.md, decided and recorded#45vjovanov wants to merge 3 commits into
vjovanov wants to merge 3 commits into
Conversation
vjovanov
changed the title
vjovanov
added a commit
that referenced
this pull request
Jul 2, 2026
vjovanov
force-pushed
the
issue-33-clickable-references
branch
2 times, most recently
from
b3cc42f to
b51d7da
Compare
vjovanov
changed the title
Resolves the clickable-references experiment (issue #33): citations in user-facing text are rendered by the writing agent, not a tool. Locally the plain §<ID> citation is the clickable form (resolution belongs to the rendering layer — productization tracked in issue #46); GitHub surfaces get agent-composed blob-URL links with the github anchor slug rule and the declaration heading as hover title; the plain citation is always the fallback. grund grows no link command; grund fmt --cross-refs stays the only link emitter, for repository Markdown. - AGENTS.md: the two-sentence convention - §DF-neural-link-generation: the decision, its rationale, the experiment record, the test matrix, and the long-form recipe Claude-Session: https://claude.ai/code/session_01DSoxRtTyph3dAC7KPMQU28
vjovanov
force-pushed
the
issue-33-clickable-references
branch
from
b51d7da to
31aad8b
Compare
…TS block v4 Productizes the clickable-citations rendering layer (issue #46). Adds the `grund integrations [<client>]` command that prints embedded terminal/editor artifacts on demand and installs them on `--write` as idempotent marked blocks — the completions/init ethos. Adds the `[render.links]` config table so the convention sentences an agent follows are a rendering of config, and bumps the AGENTS.md init block to v4 to carry a config-derived, drift-checked clickable-citations section. - FS-integrations, DF-integrations-command; FS-config §3.10, FS-init §2.3.6 - new grund-core integrations module + embedded wezterm/kitty/tmux/grund-open and an unpacked vscode TerminalLinkProvider extension - e2e goldens for the command, help within the one-screen budget, and an agent-setup-instructions step
Correctness: - wezterm.lua registered no hyperlink rule — table.insert mutated the throwaway table from default_hyperlink_rules() and discarded it. Rewritten as grund_apply_hyperlink_rule(config), which WezTerm actually reads, plus wiring instructions; the open-uri handler stays global. - install_managed_block appended on a begin marker with no matching end marker, so the next --write spliced from the orphan begin to the appended end and deleted user config in between. Now a hard error; regression test added (§FS-integrations.4.1). - kitty.conf hints regex used a capturing group, so kitty handed grund-open only the .<section> (or nothing). Now non-capturing. - grund-open EDITOR fallback assumed vim-style "+LINE FILE" and mis-quoted $EDITOR. Word-splits $EDITOR and dispatches per editor family. - write_resolver_script skipped set_executable when content already matched, leaving a non-executable resolver. Now ensures +x on that path. - Reject `integrations --write --format json` instead of running the write and silently dropping the requested format. Cleanup: - Drop json_escape_str (byte-identical to json_escape); share a RESOLVER_TARGET const between the descriptor plan and the writer. - Fold the two config-derived drift checks into one table-driven loop. - detect_clients uses `client as usize` instead of a position() scan. e2e kitty/tmux/wezterm goldens regenerated. PR #45.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Clickable citations, end to end: the convention (from #33) and its productization (#46), on one branch.
Two commits
1 — The convention (#33). Citations in ephemeral, user-facing text (agent TUI messages, PR and issue bodies) are rendered by the writing agent, not a tool: locally the plain
§<ID>is the clickable form; GitHub surfaces get an agent-composed blob-URL link whose visible text is exactly the citation; the plain citation is always the fallback.grundgrows nolinkcommand — §DF-neural-link-generation records the decision, experiment, and test matrix.2 — The productization (#46). The rendering layer that makes a plain
§<ID>actually clickable is now shipped in the binary, installable fromcargo install grund.What #46 adds
grund integrations [<client>](§FS-integrations) — prints embedded artifacts on demand (a config snippet + thegrund-openresolver forkitty/tmux/wezterm; an unpackedTerminalLinkProviderextension forvscode), detects the caller's terminal/editor from the environment when given no client, and installs on--writeas an idempotent, version-marked block — thecompletions/initethos.--format jsonemits a machine detection plan for agents. Every artifact is embedded; nothing is published to a marketplace, preserving the no-first-party-plugin stance (§FS-lsp.2.3). Why a one-time-setup command earns a CLI slot when a per-citationlinkdid not: §DF-integrations-command.[render.links]config (§FS-config.3.10) —web_base/web_ref/hover_title/local, so the convention sentences an agent follows are a rendering of repo config, not hand-edited prose. Additive, optional, validated on load; surfaced ingrund config show.### Clickable citations in user-facing textsection rendered from[render.links], drift-checked bygrund checkexactly like### Citation directions.Decisions worth a look
grund_config_versionstays 1.[render.links]is additive; the closed section/key allow-list — not the version integer — is the forward-compat net, consistent with how[citations]/[workspace]were added.--helpstill fits the 24-line one-screen budget.Verification
init,grund-core,grund-lsp(143 tests) +grund checkclean.grund-openresolving§FS-integrations→path:line;--writeappend →existson re-run → in-place update → newer-block rejection; the v4 block re-render + drift check; all deterministic prints goldened.Closes #33. Resolves #46.
https://claude.ai/code/session_01DSoxRtTyph3dAC7KPMQU28