From 662a844cf108033b5bef942c133eff2371be6e05 Mon Sep 17 00:00:00 2001
From: Torben Nehmer <torben@nehmer.net>
Date: Sun, 4 Oct 2026 19:11:35 +0200
Subject: [PATCH] fix: wiki-ingest and wiki-manage call xref add with --rel,
 not --rel-a/--rel-b (#174)

Files changed:
- CHANGES.md
- VERSION
- instructions/wiki-ingest/SKILL.md
- instructions/wiki-manage/SKILL.md
---
 CHANGES.md                        | 13 ++++++++++++-
 VERSION                           |  2 +-
 instructions/wiki-ingest/SKILL.md |  6 ++++--
 instructions/wiki-manage/SKILL.md |  5 +++--
 4 files changed, 20 insertions(+), 6 deletions(-)

diff --git a/CHANGES.md b/CHANGES.md
index 329e14d..e31f33b 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -59,7 +59,7 @@ concern - readable here, never shipped as something to parse.
 
 ---
 
-## 8.0.0-beta.38 - 2026-10-04 - kb/CONTRACT.md names unwritten scaffold sections and the Unfilled Template Sections finding
+## 8.0.0-beta.39 - 2026-10-04 - wiki-ingest and wiki-manage call xref add with --rel, not the --rel-a/--rel-b removed in 4.0.0
 
 **Author:** Torben Nehmer
 
@@ -149,8 +149,19 @@ concern - readable here, never shipped as something to parse.
 - Page-material passages in type-spec.md, type-guidance.md and language-boundaries.md name subtype templates
 - kb/CONTRACT.md names section anchors in wikilinks and the Broken Anchors finding
 - kb/CONTRACT.md names unwritten scaffold sections and the Unfilled Template Sections finding
+- wiki-ingest and wiki-manage call xref add with --rel, not the --rel-a/--rel-b removed in 4.0.0
 <!-- /wikitool:bumps -->
 
+### wiki-ingest and wiki-manage call xref add with --rel, not the --rel-a/--rel-b removed in 4.0.0
+
+Since 4.0.0 `xref add` declares one directed edge and takes a single `--rel`, but the
+cross-reference step of both skills still showed the mirrored form with `--rel-a`/`--rel-b`, so
+every session that followed it failed with `No such option` and had to recover the syntax from
+`-h`. Both now show `xref add --a --b --rel` with the reading `[A] <label> [B]` as a comment, and
+point at `kb/CONTRACT.md` § Linking for direction and reverse edges instead of restating the rule.
+A scan of every documented `wikitool` call against the command tree found no other stale flag.
+Found during an ingest in an instance on 7.0.0 (Gitea #174).
+
 ### kb/CONTRACT.md names unwritten scaffold sections and the Unfilled Template Sections finding
 
 The stage contract pairs each page property with the `lint` finding that checks it, and its
diff --git a/VERSION b/VERSION
index 66148ea..54e2684 100644
--- a/VERSION
+++ b/VERSION
@@ -1 +1 @@
-8.0.0-beta.38
+8.0.0-beta.39
diff --git a/instructions/wiki-ingest/SKILL.md b/instructions/wiki-ingest/SKILL.md
index f3bf54c..0f11928 100644
--- a/instructions/wiki-ingest/SKILL.md
+++ b/instructions/wiki-ingest/SKILL.md
@@ -343,11 +343,13 @@ validator complains - and the ticked list is the only record that they happened.
 9. **Cross-reference.**
 
    ```bash
-   tools/wikitool xref add --a "<A>" --b "<B>" --rel-a "<label>" --rel-b "<label>"
+   tools/wikitool xref add --a "<A>" --b "<B>" --rel "<label>"   # [A] <label> [B]
    tools/wikitool xref link-source --source "Source - <Title>" --entities A,B,C
    ```
 
-   The second links the new source to everything it backs in one pass.
+   The first declares one edge, on A only; which way it reads, and when the reverse edge earns a
+   call of its own, is `kb/CONTRACT.md` § Linking. The second links the new source to everything
+   it backs in one pass.
 
 10. **Check coverage.**
 
diff --git a/instructions/wiki-manage/SKILL.md b/instructions/wiki-manage/SKILL.md
index d6258da..591d407 100644
--- a/instructions/wiki-manage/SKILL.md
+++ b/instructions/wiki-manage/SKILL.md
@@ -56,10 +56,11 @@ requirements come from `tools/wikitool types describe <type>`.
 6. **Cross-reference.**
 
    ```bash
-   tools/wikitool xref add --a "<A>" --b "<B>" --rel-a "<label>" --rel-b "<label>"
+   tools/wikitool xref add --a "<A>" --b "<B>" --rel "<label>"   # [A] <label> [B]
    ```
 
-   One per relationship. Never hand-edit `related:`.
+   One per relationship, on A only; which way it reads, and when the reverse edge earns a call of
+   its own, is `kb/CONTRACT.md` § Linking. Never hand-edit `related:`.
 
 7. **Close out.** `instructions/publish-cycle.md`, `--op create`.