diff --git a/docs/agent-guide/065-logseq-cli-show-ref-id-footer.md b/docs/agent-guide/065-logseq-cli-show-ref-id-footer.md new file mode 100644 index 0000000000..97d1448de6 --- /dev/null +++ b/docs/agent-guide/065-logseq-cli-show-ref-id-footer.md @@ -0,0 +1,166 @@ +# Logseq CLI Show Referenced Entity IDs in Footer Plan + +Goal: Add a footer section to `logseq show` human output that lists referenced entities and their IDs when block content contains `[[]]`. + +Architecture: Keep the existing tree rendering unchanged and append a post-tree summary section (`Referenced Entities`) generated from refs discovered in the shown tree (and linked references when enabled). + +Tech Stack: ClojureScript, `logseq.cli.command.show`, db-worker-node thread-api pull/query via existing transport. + +Related: +- `docs/agent-guide/021-logseq-cli-reference-uuid-rewrite.md` +- `docs/agent-guide/024-logseq-cli-show-updates.md` +- `docs/agent-guide/010-logseq-cli-show-linked-references.md` + +## Problem Statement + +Current `show` output rewrites `[[]]` to readable labels, but users cannot see the stable entity ID for each reference in human output. + +When reviewing large trees or debugging graph links, users need a deterministic ID mapping without polluting every inline block line. + +The selected UX is a dedicated footer section (not inline expansion) so the tree remains readable. + +## Proposed UX + +### Human output (new footer section) + +Keep current tree output exactly as-is, then append: + +```text +Referenced Entities (2) +181 -> First child line A\nline B for wrapping +179 -> Root task for show command +``` + +Behavior: +- Section appears only when at least one reference is present. +- Order is by first appearance in rendered traversal order. +- ID should be `:db/id` (human-facing stable numeric id in CLI context). +- Label should prefer `:block/title`, then `:block/name`, then UUID string fallback. + +### Option behavior + +Provide an explicit option so users can disable the footer when needed: +- `--ref-id-footer` (boolean, default `true`) + +When `true` (default), append the footer section. +When `false`, do not render the footer section. + +Because this changes default human output, update related snapshots/tests accordingly and document the behavior in release notes. + +## Scope + +In scope: +- Human output for `show` command only. +- Single target and multi-id target modes. +- Respect existing `--linked-references` behavior for reference discovery source. + +Out of scope: +- JSON/EDN schema changes. +- Inline replacement format changes. +- New reference graph traversal semantics. + +## Design Details + +### Reference discovery source + +Build the footer map from already available tree data: +1. Traverse `:root` tree nodes and gather references from text fields (`:block/title`, `:block/name`, `:block/content`). +2. If linked references are enabled, include linked reference block texts too. +3. Reuse existing UUID extraction and label fetch behavior where possible. + +### UUID to entity resolution + +Current logic already fetches labels for UUID refs. Extend resolution to also fetch `:db/id` for each referenced UUID: +- Pull selector should include `:db/id`, `:block/uuid`, `:block/title`, `:block/name`. +- Build map: `uuid-lowercase -> {:id :label