Skip to content

fix(collect): an embed of an attachment card draws and ships its payload - #11

Merged
adammharris merged 1 commit into
mainfrom
agent/backlog-an-id-embed-of-a-card-draws-its-payload
Oct 20, 2026
Merged

adammharris merged 1 commit into
mainfrom
agent/backlog-an-id-embed-of-a-card-draws-its-payload

Conversation

@adammharris

Copy link
Copy Markdown
Member

Closes the task docs/tasks/an-id-embed-of-a-card-draws-its-payload.md (marked status: done in this branch).

What changed

collect_documents has a new step, retarget_cards, that runs after the visibility filter and before rewrite_id_links. For each body reference that resolves to an attachment card (a local id:, a self-qualified id:, or a path to the sidecar), it does this:

  • Embed (![](id:<card>), ![](photo.jpg.yaml)): the reference is retargeted to the payload, written relative to the page. The locator and wrapper are kept.
  • Plain link, card published: left alone, so it lands on the card's page as before.
  • Plain link, card not published: retargeted to the payload, the same way an embed is.

The existing reference scan then sees the payload's path, so the payload is shipped, or withheld when its sidecar names another audience. These are the same rules a reference by the payload's own path gets. Ids are looked up in CollectOptions::id_by_path read backwards. The anchor handling in push_canonical_ref moved into a small canonical_target helper that both steps share.

Foreign cards (id:<other-workspace>/<id>) are left as they were. Their payload belongs to their own workspace.

Why

Before this change, ![](id:<card>) became ![](/trip/photo.jpg.md), the card's own source path. The published <img> pointed at a page or a YAML file, and the payload was never shipped.

Verification

  • I wrote three tests before the fix and saw all three fail with the bug described in the task:
    • an_embed_of_a_card_draws_its_payload: by id and by path, card published and unpublished
    • a_link_to_a_card_lands_on_its_page_or_else_its_payload
    • an_embed_of_a_card_for_another_audience_is_withheld
  • After the fix, ship ci passes all jobs locally: fmt, clippy -D warnings, tests, docs, wasm, alone, MSRV 1.88.
  • prov check: no findings.

An `id:` reference to an attachment card resolved to the card's own
source path, so `![](id:…)` drew a page or a YAML file and the payload
never shipped. An embed of a card, by id or by a path to the sidecar,
now names the payload, relative to the page, before the id rewrite
runs; a plain link does the same when the card is not one of the
site's pages. The reference scan then collects or withholds the payload
as it does one referenced by its own path.

Behavioural-change: a body embedding an attachment card (`![](id:<card>)` or `![](photo.jpg.yaml)`) is collected with the reference retargeted to the payload, and the payload is shipped or withheld; a link to a card the site does not publish lands on the payload rather than the card's source path.
@adammharris
adammharris merged commit 7827104 into main Oct 20, 2026
8 checks passed
@adammharris
adammharris deleted the agent/backlog-an-id-embed-of-a-card-draws-its-payload branch October 30, 2026 01:25
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant