Library: your curated asset shelf

Every asset Forge produces lands in two places now. The raw artifact (PNG, WAV, JSON descriptor, GLSL source) goes under <project>/.forge/generated/<kind>/<timestamp>.<ext> like before. Alongside it, a curated library entry at <project>/.forge/library/<kind>/<slug>.toml references the artifact and gives you the user-facing handle: a name you choose, tags, a stable id, and a discoverable home in the Library tab of the left sidebar.

The library is what you’re meant to browse, search, rename, and clean up. The generated/ directory is the back-store. You can ignore it entirely and live in the library.

What a library entry looks like

<project>/.forge/library/palette/sunset-warm-3a7c9b.toml:

id = "01923456-789a-7bcd-8def-0123456789ab"
kind = "palette"
name = "Sunset Warm"
slug = "sunset-warm-3a7c9b"
schema = 1
created_at = "2026-05-07T19:34:21Z"
updated_at = "2026-05-07T19:41:08Z"
tags = ["warm", "sunset"]
notes = ""

[params]
harmony = "split"
ramp_steps = 5
color_count = 7

[[artifacts]]
role = "descriptor"
path = ".forge/generated/palettes/20260507-193421-094.json"

Three identifiers, each with a job:

Field	Mutable	Used for
id	never	Cross-asset references (UUIDv7, time-sortable)
slug	yes (with care)	Filename stem
name	yes (free)	Display in the UI

Renaming an entry rewrites name and regenerates slug; the file is renamed atomically. Cross-references between entries (a Scene that links to a Palette, an Animation that links to a Sprite Sheet) resolve by id first with path fallback, so renames don’t break anything downstream.

The Library tab

The left sidebar in project mode has a tab switcher: Files (the project tree) | Library (curated entries). Click into Library and you get:

• Type chips at the top (All, Palettes, Scenes, Levels, Parallax, Sprite sheets, Tilemaps, Tilesets, Shaders, Animations, Dialog, Voice, SFX, Music).
• Search box with prefix syntax: kind:scene tag:tier-c forest dusk filters by kind, tag, and freeform name/tag/notes substrings.
• Sort dropdown (newest first, oldest first, name A→Z, name Z→A).
• Refresh button (file watcher catches most changes; this is the manual override).
• List / grid toggle.

Right-click any entry for Rename, Edit tags, Reveal in Explorer, and Delete.

For a bigger browse view, run Open Library from the command palette (Ctrl+Shift+P). It opens a Library tab in the workspace with the same data and same actions, just larger thumbnails.

Save vs Export

These are two different verbs in Forge.

Save writes the canonical descriptor + library entry to .forge/. Every tool tab’s Save button does only this. Cheap, instant, what the user means by “save my work.”

Export writes a non-Forge interchange format (.gpl for GIMP palettes, .css variables, copies of .tmj / .glsl / .png+.json atlases) to a deliverable directory the user’s engine can import. The destination is engine-aware based on detected project mode:

Detected engine	Export root	Why
Unity	<project>/Assets/Forge/<kind>/	Unity imports anything under Assets/ and auto-mints .meta files
Godot	<project>/forge/<kind>/	Reachable as res://forge/<kind>/
Web (Phaser / Three.js / vanilla) with public/	<project>/public/forge/<kind>/	Vite static-served convention
Web with assets/ (no public/)	<project>/assets/forge/<kind>/	Same idea, alternate static dir
Generic / undetected	<project>/exports/<kind>/	Conservative fallback

Tabs that emit non-Forge formats now ship an explicit Export button next to Save:

• Palette: drops down a hex/css/gpl format picker.
• Shader: copies .glsl / .frag.
• Tilemap: copies the Tiled .tmj.
• Sprite sheet + Aseprite atlas: copies the PNG (binary) + JSON.

The library entry and the engine export are independent: you can Save an asset to your library and never export it (great for prototyping), or Save and Export every time (great for a tight engine iteration loop).

Auto-export on save

Settings → Workspace → Auto-export on save. Per-kind toggles (palette, shader, tilemap, spritesheet). When ON for a kind, that tab’s Save also fires its Export silently to the engine path. Off by default so users who don’t care about engine pipelines never see surprise files in Assets/Forge/.

Migration from existing projects

Open the Library tab in a project that has pre-existing .forge/generated/ artifacts and Forge runs a one-time migration: each descriptor becomes a library entry referencing the existing files. Names come from the descriptor’s prompt / name field (truncated to 60 chars) or fall back to <kind> <timestamp>. The original files in generated/ aren’t moved or renamed. A marker file .forge/library/.migrated records the pass; subsequent Library opens are cheap.

Migration is additive: forge-link blocks in your old chat history that pointed at .forge/generated/... paths keep working. Click them and you still land in the proper editor tab.

Soft delete + 30-day TTL

Deleting a library entry moves it to .forge/.trash/<id>.toml with a deletion timestamp. The underlying generated files stay in place — only the curated handle is gone. Restore is one click (Right-click in the Trash view → not yet shipped; hand-edit the trash file’s contents back to .forge/library/<kind>/ if you need it before then).

Trash entries older than 30 days auto-purge on the next project switch. The TTL isn’t configurable in v1; if you need a longer grace period, copy the trash file out before the deadline.

Inbound references on delete

When you delete an entry that other entries reference (e.g. a palette that a scene links to), the confirm strip shows the count and a clickable list of the referencing entries. Click any inbound entry to jump to it before confirming. The reference itself uses the entry’s id, so even after rename the link survives — but if you delete the source, the dependent entry will resolve to “missing” the next time you open it.

Cross-asset refs in your own entries

If you’re hand-editing a .toml to wire dependencies (rare but supported):

[[refs]]
to_id = "01923456-789a-7bcd-8def-0123456789ab"
to_path = ".forge/library/palette/sunset-warm-3a7c9b.toml"
role = "palette"

Resolution is to_id first, to_path as fallback. Renaming the palette breaks neither; deleting it surfaces in the inbound-ref scan when someone tries to delete the dependent.

Where library entries appear

• Files tab in the left sidebar: under .forge/library/<kind>/ (collapsed by default). Each .toml shows the persimmon star glyph.
• Library tab in the left sidebar: the daily-driver curated view.
• Workspace tab: bigger view via command palette (Ctrl+Shift+P → “Open Library”). Singleton — opening twice reuses the existing tab.
• forge-link cards in chat history: the agent-side path keeps emitting .forge/generated/ paths so historical previews never break, but the curated entry is what shows up when you browse.