Forge-link blocks

A forge-link block is how the agent surfaces an asset it has just generated or saved. Forge parses the block out of chat messages and renders an inline preview card with a media-typed preview and a click-to-open button that opens the asset in the right editor tab.

This is the asset-side companion to the proposal blocks. Proposals propose changes that need approval. Forge-link blocks just embed and link. There’s nothing to approve.

When the agent uses it

After saving a non-image asset (audio clip, palette, sprite sheet, tilemap, shader, parallax scene), or to surface an existing project file in the right editor. Generated images don’t need a forge-link because Codex’s built-in image tool already renders them inline.

Format

```forge-link
path: .forge/generated/sfx/jump_001.mp3
preview: audio
open_in: audiotrim
label: Jump SFX (0.4s)
```

Fields

• path (required): project-relative path to the asset (absolute paths are also accepted). Cannot contain ... In open mode without an active project, relative paths are shown without a working preview but the click still attempts to open the asset.

• preview (required): one of audio, image, palette, spritesheet, tileset, tilemap, shader, parallax. Determines the inline preview shape.

• open_in (optional): the tab kind to open on click. If omitted, defaults follow preview:

  preview	default open_in
  audio	audio
  image	image
  palette	palette
  spritesheet	spritesheet
  tileset	tilemap
  tilemap	tilemap
  shader	shader
  parallax	parallax

  Override to audiotrim for audio clips you want the user to crop, for example.

• label (optional): short human-readable name. Falls back to the file name.

Preview shapes

Each preview value produces a different inline card:

• audio: waveform thumbnail, play/pause button, click-to-seek. The card lives in chat history. Reopening the chat later replays the clip.
• image: thumbnail (max ~192px tall), click to open the full image viewer.
• palette, spritesheet, tileset, tilemap, shader, parallax: typed placeholder card with the right icon and a click-to-open button. Slice-by-slice rollouts replace these placeholders with real per-kind previews.

Authoring rules

• One block per asset. Don’t bundle multiple paths in one block.
• Place the block immediately after the prose describing the asset, in document order. The user reads “Here’s the punchy variant:” → preview → “Here’s the soft one:” → preview, in the order the agent wrote them.
• In project mode, pair the forge-link with a forge-propose append to ASSETS.md so the project’s memory keeps a durable log of what was generated.
• Don’t re-state the asset in prose after the block. The card carries enough context.

Persistence

The block lives in the assistant message’s text, exactly as written. Re-rendering the chat (after a session restart, project reopen, or git checkout) re-parses the block and re-renders the card. Audio previews re-decode the file from disk on each render, so they stay playable as long as the path resolves.

Path resolution

Forge resolves path to an absolute path in this order:

1. If the path is absolute (drive letter, leading /, or UNC \\), use as-is.
2. If ~/..., leave unresolved (the renderer can’t expand home).
3. Otherwise, join against the active project path.

Unresolved paths still render a card, but the preview body shows an error and the click button opens the matching tab without a target file.

Why not a regular markdown link?

Markdown links go to URLs. They don’t know about Forge’s tab system, can’t render an inline preview, and can’t disambiguate “open this audio in the player” vs “open this audio in the trimmer”. A typed block keeps the affordances right and lets each preview kind evolve independently.