Add stable block identities and robust metadata syntax

[adrianbrowning]

What to build

Make Markdown code blocks reliably addressable across listing, synchronization, validation, and CI. Metadata should support stable identities and values that are practical for real-world filenames and labels.

Acceptance criteria

• Blocks can declare a stable documented identifier or name.
• Every relevant command can select a block by that identifier.
• Duplicate identifiers are detected with actionable errors.
• Metadata supports quoted or escaped values, including paths and labels containing spaces.
• Listing output exposes the identity and documentation shows selection examples.

Blocked by

None - can start immediately

[adrianbrowning]

This was generated by AI during triage.

Agent Brief

Category: enhancement
Summary: Add stable per-document block names and robust quoted metadata values.

Current behavior:
Code-block metadata is parsed by splitting the info string on whitespace. Values therefore cannot contain spaces, malformed input is mostly ignored, identifiers are not validated for uniqueness, and only the run command offers partial name-based selection.

Desired behavior:
A Markdown code block can declare a stable name using name=. Names are unique within one Markdown document; a cross-document reference is the document path plus the name. Every block-oriented CLI command can select by that name. Metadata continues to support existing unquoted key=value values and adds double-quoted values with spaces, backslash escapes, and quote escapes.

Key interfaces:

• Fence metadata grammar — preserve existing unquoted values; accept name="quick start" and file="examples/getting started.ts". Inside quoted values, " represents a quote and \ represents a backslash.
• Metadata validation — reject unterminated quoted values, invalid escape sequences, duplicate keys in a fence, and duplicate names in the same document with actionable errors.
• Command filtering — make --name available consistently across list, extract, update, run, and dump.
• Listing — display the declared name as block identity in human-readable output and expose it structurally for machine-readable output.

Acceptance criteria:

• Blocks accept an optional name metadata value as their stable identifier.
• Every block-oriented command supports selecting by --name.
• Duplicate names within one Markdown document fail before the selected operation runs and identify the conflicting names/locations.
• Existing unquoted key=value metadata remains compatible.
• Double-quoted values support spaces, escaped quotes, and escaped backslashes.
• Unterminated quotes, invalid escapes, and duplicate metadata keys produce actionable errors.
• Listing and documentation show the block name and selection examples.
• Parser, command, and CLI integration tests cover successful and failing cases.

Out of scope:

• Requiring every block to have a name.
• Global uniqueness across multiple Markdown documents.
• Position-derived identifiers or automatic naming.
• Defining the versioned JSON response envelope; that follows in issue Add a versioned machine-readable CLI contract for agents #5.

Verification status:
Confirmed: metadata is currently whitespace-split, names are not validated, and --name exists only for run.