feat: merge Docusaurus and Gitea documentation skills

references/cross-linking-source-and-derived-dossiers.md

@@ -0,0 +1,63 @@
+# Cross-linking source dossiers to generated derived dossiers
+
+Use this pattern when canonical entity pages contain observations that are consolidated into generated records such as systems, suppliers, or projects.
+
+## Objective
+
+Add a generated column to each source observation table that displays the derived record's internal ID and links to its documentation route, without editing the canonical source corpus or duplicating identity logic.
+
+Example:
+
+```md
+| Service or system | System dossier | Relationship | Evidence | Confidence |
+|---|---|---|---|---|
+| PPVIS | [`SYS-2D859CB9C5`](/org/repo/systems/ppvis-2d859cb9c5/) | operates | … | high |
+```
+
+## Generation pattern
+
+1. Parse canonical source tables and retain a stable observation locator, normally `(source_file, source_line)`.
+2. Run the canonical identity/consolidation algorithm once.
+3. When assigning each derived record its ID and slug, annotate every contributing observation with both values.
+4. Return an observation-link map from the derived-registry generator:
+
+```python
+{
+    (observation["source_file"], observation["source_line"]): {
+        "id": observation["derived_id"],
+        "slug": observation["derived_slug"],
+    }
+}
+```
+
+5. Generate MDX-safe source dossier copies. Add the new table header and inject one link into each data row using that map.
+6. Leave canonical source Markdown unchanged; generated display enrichment belongs in the publishing layer.
+
+## Coverage invariant
+
+Generation must fail when any parsed observation is not linked:
+
+```python
+expected = sum(1 for source, _line in observation_links if source == source_file)
+if linked != expected:
+    raise SystemExit(
+        f"derived-link coverage mismatch in {source_file}: "
+        f"linked={linked} expected={expected}"
+    )
+```
+
+After generation, independently verify:
+
+- displayed link count equals the registry observation count;
+- every `(ID, slug)` target exists in the generated registry;
+- the number of unique targets equals the expected derived-record count;
+- representative legacy and structured table formats render correctly;
+- the full Docusaurus production build and route validator pass.
+
+## Important pitfalls
+
+- Do not recompute identity independently in the source-page generator. Reuse the canonical registry result or links will drift when aliases change.
+- Do not match only by displayed label; duplicate labels and client-scoped generic resources make that unsafe.
+- Do not use the internal ID as a guessed route. Display the ID, but link with the generated canonical slug.
+- Preserve numeric source line locators until enrichment is complete. Transformations such as frontmatter injection or `<br>` normalization can otherwise shift line numbers.
+- Ensure generated internal links are not collected into public-source References indexes; references should remain provenance links, not site-navigation links.