Skip to content

Viewing and Editing Artifact Metadata

The Metadata tab in the artifact modal shows structured information about an artifact's frontmatter, tool declarations, provenance, and upstream source. In local edition, whitelisted fields can be edited inline and the changes are written back to the source file automatically.

Viewing Metadata Sections

Open any artifact modal on the /artifacts page and select the Metadata tab. Four sections are displayed:

Overview

Displays all frontmatter fields stored in the database (description, author, version, license, model, effort, permission_mode, user_invocable, and any custom metadata_json keys). Read-only fields are visually muted with no hover affordance. Tags are excluded here — use the dedicated Tags tab to manage them.

Tool Declarations

Lists the canonical tool declarations extracted during ingestion: tool name, selector, risk level, declaration kind, source platform, and confidence score. For artifacts ingested before the tool-graph migration, a legacy tools_json flat list is shown instead, with a notice indicating the pre-migration fallback.

Enterprise administrators also see a Trust State badge per declaration (read-only for non-admins; editable by users with artifact:admin scope in edit mode).

Provenance

Shows raw-metadata parse rows: source path, parser name, parser version, parse status, and any parse warnings. This section is read-only on all editions. If no provenance data is available (pre-migration artifact or parser not yet run), a "Metadata not available" notice is shown instead.

Upstream

Displays upstream-source fields from the artifact record (origin URL, upstream binding, last-seen version). This section is always read-only.

Entering Edit Mode (Local Edition)

Edit mode is available in the local edition when the artifact_metadata_edit_enabled feature flag is enabled by an operator.

  1. Open the Metadata tab in the artifact modal.
  2. Click the Edit button in the top-right corner of the tab. An Edit / Save / Cancel bar appears at the bottom.
  3. Modify fields using the controls provided (see Editable Fields below).
  4. Click Save (or press Enter in any field) to apply changes. Click Cancel (or press Escape) to discard.

Changes are applied optimistically — the UI updates immediately before the API responds. If the save fails, the UI rolls back to the previous values and shows an error notification.

Editable Fields

Only whitelisted frontmatter fields can be edited. Non-whitelisted fields, the Provenance section, the Tool Declarations section (except trust state for enterprise admins), and the Upstream section are always read-only.

Field Input Type Validation
description Textarea Max 1000 characters
author Text Max 200 characters
version Text Semver or free text, max 50 characters
license Combobox (SPDX list) Must match an SPDX identifier or be left blank
model Combobox (known model IDs) Must match a known model identifier or be left blank
effort Select Valid effort values only
permission_mode Select Valid permission-mode values only
user_invocable Toggle Boolean
Custom keys Text / Textarea DB-only write (no source file write-back for custom keys)

Inline validation fires on blur and again when you attempt to save. Invalid fields block the save and show an error message below the input.

Local Write-Back Behavior

When you save a change in local edition, SkillMeat:

  1. Validates the frontmatter YAML before writing anything.
  2. Writes the updated frontmatter to the source file atomically (temp file + rename — no partial writes).
  3. Creates a new CAS blob with the updated content hash; existing blobs are never mutated.
  4. Updates the ArtifactVersion content tree and lockfile hash to reference the new blob.
  5. Commits the database record first; if the filesystem write subsequently fails, the DB change is kept and a warning is logged (non-blocking).

After a successful save, the artifact detail cache is invalidated and the modal reloads from the server.

Enterprise Edition Differences

Behavior Local Edition Enterprise Edition
Edit mode availability When artifact_metadata_edit_enabled flag is on Same flag required
Write destination Source file + database Database only (no filesystem write-back)
CAS blob creation Yes — new blob per edit No
Trust State editing Not available Available to users with artifact:admin scope
Custom key edits DB-only DB-only

Troubleshooting

Edit button is not visible — The artifact_metadata_edit_enabled feature flag is off. Ask your operator to enable it in APISettings.

"Metadata not available" notice in Provenance — The artifact was ingested before the tool-graph migration. Provenance data will appear after the next re-parse or re-sync of the artifact.

Save fails with a validation error — Check the inline error message below the relevant field. Correct the value and try again.

Save succeeds but source file does not update — In enterprise edition, writes are database-only by design. In local edition, check the API logs for a write-back warning.