---
name: docxology/template-manuscript-cross-references
source: https://app.decimal.ai/s/docxology-template-manuscript-cross-references@1/SKILL.md
source_sha256: 82e8a05baf51
---

# Manuscript cross-references (registry tokens)

For Pandoc-crossref `@fig:` / `[@key]` exemplars, see [`docs/guides/manuscript-semantics.md`](../../guides/manuscript-semantics.md). This skill is for **YAML registry + inline tokens**.

> **Convention, not built-in infrastructure.** `refs/labels.yaml` and `[[FIG:]]`/`[[THMREF:]]`/`[[VAR:]]` tokens are a project-authored convention, not a dedicated parser in `infrastructure/`: no current public exemplar under `projects/templates/` uses this style (all ship Pandoc-crossref), and there is no `labels.yaml`-specific validator. Validation for a project that adopts this convention still runs through the generic `infrastructure.validation.cli markdown`/`prerender` checks below plus project-local test coverage the project author writes — token expansion is the project's own `manuscript_variables.py`-style substitution, not a shared registry engine.

## Natural invoke

- "Audit [[FIG:]] tokens in actinf_policy_entanglement_lean manuscript"
- "Hard-coded section numbers in prose — tokenize them"
- "labels.yaml has orphan keys"

## Inputs to confirm

- **Scope** — `projects/<name>/manuscript/` path or project name.
- **Style** — confirm registry/token vs pure Pandoc-crossref (do not mix styles in repairs).

## Workflow

1. **Registry truth** — `refs/labels.yaml` (figures, equations, sections, theorems) and `refs/citations.yaml` or hybrid `references.bib`. Every token label must exist; every `[@citekey]` must resolve.

2. **No hard-coded numbers** — prefer `[[THMREF:…]]`, `[[SECREF:…]]`, `[[FIGREF:…]]`, `[[EQREF:…]]` over "Theorem 7.3", "§8", "Figure 2" in body prose.

3. **Captions** — YAML-stored captions may not expand `[[…]]` unless renderer documents second pass.

4. **Sync** — subsection headings and `labels.yaml` section/theorem numbers aligned; grep for stale numbers after renumbering.

5. **Bibliography** — if `99_*` uses `[[CITELIST:all]]`, do not hand-maintain a parallel list.

6. **Report** — missing/orphan/duplicate keys; hard-coded numbers to tokenize; concrete edits (file + snippet).

## Verification commands

```bash
uv run python -m infrastructure.validation.cli markdown projects/<name>/manuscript/
uv run python -m infrastructure.validation.cli prerender projects/<name>/manuscript --repo-root .
```

## When NOT to use

- **Full manuscript scaffold** → [manuscript-creation](../manuscript-creation/SKILL.md)
- **Triple-check every factual claim** → [manuscript-claim-verification](../manuscript-claim-verification/SKILL.md)

## References

- [`docs/rules/manuscript_style.md`](../../rules/manuscript_style.md)
- Project-local `manuscript/refs/README.md` when present