---
name: mdc
description: Read, edit, and author Theriety Notion-backed MDC files safely with native text tools while preserving the private parser grammar and ref identity. Use for company MDC body changes; keep transport and conflict orchestration in the Alvis specification skills.
requirements:
  model: capable
  effort: deliberate
argument-hint: "[<path-to-.mdc>] [--mode=read|edit|author]"
---

# Theriety MDC

Safely read or author Notion-backed MDC (`@theriety/mdc`) while preserving its block tree, annotations, refs, closing markers, and YAML frontmatter.

## Boundaries

- This is the only skill that authors Theriety-dialect `.mdc` body content. `notion-sync` may materialize transport files or update pairing metadata through `specification:sync-notion`, but callers must not hand-edit MDC.
- Specification callers bind this skill exactly as `--body-author=specification:mdc` and pass that selector unchanged through the operation chain. Accept only the already approved body and exact path; never select identity, transport, or authority here.
- `.mdc` is reserved for Notion-backed files. In state-managed work, author only an exact path explicitly supplied by the caller, returned by transport, or recorded in the active work pairing. A project may conventionally keep a mirror beneath `.state/`, but this skill does not require or derive it.
- `last_edited_time` is remote revision metadata owned by Notion transport. Local read, edit, and author flows never add, stamp, or rewrite it. Record a local edit time in work evidence or a receipt, not in MDC frontmatter.
- Do not derive or rename notion-sync paths, sync to Notion, or promote durable project documentation or work-state content here.
- Refuse a non-`.mdc` target, ambiguous edit location, or operation requiring the parser runtime rather than safe text editing.

## Inputs

- **Required**: target `.mdc` path, or destination plus content for authoring.
- **Optional**: `--mode=read|edit|author`; otherwise infer from existence and request verb.

## Mandatory invariants

<IMPORTANT>
1. Indent exactly two spaces per nesting level; never introduce tabs.
2. A block annotation is immediately adjacent to its target block.
3. Frontmatter, when present, starts at byte zero, uses exact `---` delimiter lines, and is valid YAML.
4. Annotation bodies are YAML object syntax and close on the same line.
5. Inline annotations immediately follow `]` or `)`.
6. Every closing marker is `--{ ref: <name> }--`, matches the opening ref, and has the opening block's indentation.
7. Preserve required escapes outside parser-opaque fenced code.
</IMPORTANT>

Full grammar, including closing-marker rules: [references/syntax.md](references/syntax.md).

## Workflow

1. For `edit` and `author`, follow the injected `essential:references/state.md` resolver and artifact-write gate; read mode remains non-mutating. Use paths only from `resolved`, and follow its `work_id_required`/`requires_ignore` main-agent and worker dispositions exactly. Validate that an engineering MDC target is the exact caller-supplied, transport-returned, or active-work-paired path within its declared output root. Before authoring at a transport-mirror path, independently require that root to be ignored and untracked; otherwise return `requires_ignore` with its owning workspace's exact `ignore_file`. Read only the active-work pointers required to validate the target.
2. Load mode references before touching content: every mode → syntax; `edit` additionally loads [references/editing-rules.md](references/editing-rules.md); `author` additionally loads [examples/idioms.md](examples/idioms.md).
3. Locate non-trivial edits by `ref:`, unique text, or exact line range, then read enough surrounding structure to determine parentage and indentation. Before mutation, capture the exact values and multiplicity of transport- owned frontmatter, including `ref`, `parent`, and `last_edited_time`, so the post-edit check can prove they did not drift. For a locally authored, unsynced page, omit `last_edited_time`; only transport may populate it.
4. Apply the smallest coherent operation. Safe edits include annotation scalar changes, same-type text replacement, and correctly indented child append. Confirm before moving/deleting a subtree, changing inferred type, or renaming a referenced `ref:`. Preserve notion-sync frontmatter and path.
5. Re-read every modified region and apply the invariant checklist. Preserve existing markers; add the stringifier-default marker to a ref-bearing block when it gains children; remove an orphan only when its last child is removed.
6. After all changed MDC files pass review, invoke the generic transport owner once in read-only metadata mode:

   `specification:sync-notion validate-metadata path/to/a.mdc path/to/b.mdc`

   That operation must not change file bytes or interpret body grammar. Compare its reported values to the pre-edit capture and reject any local change to transport-owned metadata. Store local edit timestamps, if useful, only in work evidence/receipts. Investigate any refusal.
7. Return explicit final paths generated or materially rewritten as `generated_files`.

## Verification

- A fresh read passes all syntax, indentation, adjacency, marker, and YAML checks for each changed region.
- The read-only metadata validation covered exactly the changed edit/author files once at the end and did not change their bytes.
- Path and all transport-owned metadata, including `ref:`, `parent:`, and `last_edited_time`, remain byte-for-byte stable during local authoring.

## Completion

Report mode, file paths, refs and operations, marker disposition, invariants, transport-metadata validation, the work-evidence location for any local edit time, and `generated_files`. Read mode reports an empty manifest. A refusal names the boundary and the required ref or exact target.