apresmoi Jiang Provenance Linker
Use this when the main task is linkage: source spans, evidence hovers, lens points, backlinks, transcript jumps, or validation of those surfaces.
Source Refs
Use versioned refs:
video:<source-slug>@transcript:v1#seg-0001
article:<article-id>@text:v1#p-0001
interview:<interview-id>@transcript:v1#seg-0001
Do not invent refs. Verify target segments exist.
Markdown Evidence Marks
Use:
[visible phrase]{evidence="video:<source-slug>@transcript:v1#seg-0001"}
Rules:
- Mark the phrase or clause that the source supports.
- Keep refs minimal but sufficient.
- Put the strongest direct ref first.
- Do not mark unsupported synthesis.
- Do not leave raw ref dumps in public reader pages.
Lens Points
Lens point syntax:
<!-- lens-point id="stable-id" concept="concept-family" evidence="video:<source-slug>@transcript:v1#seg-0001" -->
<span id="stable-id" class="lens-point-anchor"></span>
Compact reusable idea text...
Rules:
- IDs are lowercase, hyphenated, stable, and unique.
- Evidence must support the point, not only the general topic.
- The visible block should be compact enough for a hover card.
- Preserve IDs when moving or improving the same idea.
Episode To Lens Links
Episode marks can cite existing lens points:
{
"text": "The guide is part of the trap.",
"lens_points": ["lens-point:guide-trap-necessary-guide"],
"refs": [
"video:predictive-history-6m1z-v3wgok@transcript:v1#seg-0014"
]
}
Only link a phrase to a lens point when both are specific enough. The episode phrase needs source refs, and the lens point must already exist in generated link data.
Validation
Run:
node ops/scripts/compile-content.mjs
node ops/scripts/validate-content.mjs
Inspect generated link data when needed:
node -e "const i=require('./website/src/data/lens/link-index.json'); console.log((i.lens_points||[]).map(p=>p.id+' -> '+p.url).join('\n'))"
For website-visible changes, run:
cd website && npm run build