@antoneeo/kb-agentic-skill 1.1.0 → 1.2.0

package/README.md

@@ -23,11 +23,12 @@ Deliberately absent: any per-node coverage or completion state. `gaps:` says wha
 ## Key features
 
 - **Risk-proportional triage, measured in knowledge and never in files**: one claim row → propagating a fact already settled → a new knowledge unit (a source ingested, a node created or superseded, the hierarchy moved). Carrying one settled fact into eight documents is small; one claim that re-parents a node is not. A **Write Triggers** table maps each knowledge event to exactly one destination.
+- **Portable knowledge**: `export` bundles a subgraph together with the bytes its claims cite — a closure, not a selection, because a claim whose source cannot be reopened is model knowledge arriving by another route. `import` merges it into another project **additively**: it never overwrites a node and never deletes, and claims already present are recognised by id rather than by comparing text, since the same artifact cited at the same span mints the same id in every project. Knowledge crosses the project boundary; **authority does not** — an imported ruling arrives as `prov: IMPORTED`, keeps its original `basis:`, and cannot settle a local disagreement until you re-ratify it.
 - **Vision-guided governance**: Standalone projects use `ai_docs/vision/`; Hybrid projects use devPNT `M-VISION` as the milestone north star. `DRAFT` informs, `APPROVED` binds, promotion is the user's alone.
 - **Independent review, twice**: the design before it is implemented, the result before it is declared done — fresh-context subagent > one-shot run > a declared self-pass, 3 rounds max, one log line each, and a PASS is invalid on "found nothing".
 - **Question discipline**: a question is legal only when the agent searched first, names the search with its result, and names the decision it unblocks; otherwise it proceeds on a declared assumption, batched.
 - **Operative guides + agent-global KB**: distil user-provided indications into source-faithful `GUIDE_*.md` (`source_kind: document`) — verbatim snapshot plus hash, so drift is detected mechanically.
-- **Mechanical checks**: `check`, `validate`, `index`, `graph`, `corpus`, `claim-id`, `anchor`, plus the spine's `stale`/`mark`/`gate`/`plan`/`orient`/`migrate`. The graph and corpus checks verify spans against the stored extraction, recompute every id, refuse cycles and unreachable nodes, and enforce `CONTESTED` symmetry.
+- **Mechanical checks**: `check`, `validate`, `index`, `graph`, `corpus`, `claim-id`, `anchor`, `export`, `import`, plus the spine's `stale`/`mark`/`gate`/`plan`/`orient`/`migrate`. The graph and corpus checks verify spans against the stored extraction, recompute every id, refuse cycles and unreachable nodes, and enforce `CONTESTED` symmetry.
 - **Installed support files**: Claude, Codex, Gemini and Google Antigravity receive the full skill folder — `SKILL.md`, `templates.md`, `taxonomy.md`, `distillation.md`, `reconciliation.md`, `guides.md`, `vision.md`, `elicitation.md`, `review.md`, `dispatch.md`, `routing.md`, `ENFORCEMENT.md`, and the validator's two files, `scripts/sdlc_check.py` + `scripts/sdlc_core.py` (the core is the family's shared spine — copy both, or neither).
 
 ## Installation

package/gemini-extension.json

@@ -1,6 +1,6 @@
 {
   "name": "kb-agentic-skill",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "Knowledge-Base & Document-First protocol with risk triage, Vision governance, signal distillation and optional devPNT integration.",
   "author": "Antonio Pinto (https://github.com/Antoneeo)"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@antoneeo/kb-agentic-skill",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "Knowledge-Base & Document-First protocol for Claude Code, Gemini CLI, Google Antigravity and Codex with risk triage, Vision governance, signal distillation and optional devPNT integration.",
   "keywords": [
     "claude-code",
@@ -36,6 +36,7 @@
     "skills/kb-agentic-skill/review.md",
     "skills/kb-agentic-skill/dispatch.md",
     "skills/kb-agentic-skill/routing.md",
+    "skills/kb-agentic-skill/portability.md",
     "skills/kb-agentic-skill/ENFORCEMENT.md",
     "skills/kb-agentic-skill/scripts/sdlc_check.py",
     "skills/kb-agentic-skill/scripts/sdlc_core.py",

package/skills/kb-agentic-skill/SKILL.md

@@ -13,6 +13,7 @@ This skill guides knowledge management and documentation with a Document-First p
 
 Support files in the skill directory:
 - `templates.md`: templates for Vision, Knowledge ANALYSIS, Research SPIKE, SOP GUIDE, audit plan, and handoff.
+- `portability.md`: carrying knowledge between projects — what a bundle is, why export is a closure rather than a selection, and the rule that knowledge crosses a project boundary while authority does not (`prov: IMPORTED`). Read before `export`/`import`.
 - `taxonomy.md`: placing a claim in the topic graph — descent over the generated index, the five verdicts (EXISTS / INADEQUATE / MISSING / GENERALIZES / UNPLACED), the sibling rule, guarded re-parenting, canonicalization. Run at L3 before drafting.
 - `guides.md`: pipeline for distilling user-provided indications into `ai_docs/reference/GUIDE_[topic].md`.
 - `vision.md`: how to write a Vision a cold reviewer can actually apply — the properties that make a rule hold, the minimum operable sections, and the blind check.
@@ -21,7 +22,7 @@ Support files in the skill directory:
 - `review.md`: the review discipline — when a review is due, how to request one, how to receive findings, how to review.
 - `dispatch.md`: opt-in subagent execution of an approved plan.
 - `routing.md`: which lens owns this unit of work. Read ONLY when a sibling lens skill is installed alongside this one; a single-lens install never reads it.
-- `scripts/sdlc_check.py` + `scripts/sdlc_core.py`: the mechanical validator for the docs root (`check`, `validate`, `index`, `stale`, `mark`, `gate`, `plan`, `orient`, `migrate`, and the knowledge overlay: `graph`, `corpus`, `claim-id`). Two files: the core is the family's shared spine; the entry point IS the knowledge overlay — the claim ledger and topic-graph checks live inside it, so the core alone runs none of them. Copy both, or neither.
+- `scripts/sdlc_check.py` + `scripts/sdlc_core.py`: the mechanical validator for the docs root (`check`, `validate`, `index`, `stale`, `mark`, `gate`, `plan`, `orient`, `migrate`, and the knowledge overlay: `graph`, `corpus`, `claim-id`, `anchor`, `export`, `import`). Two files: the core is the family's shared spine; the entry point IS the knowledge overlay — the claim ledger and topic-graph checks live inside it, so the core alone runs none of them. Copy both, or neither.
 - `ENFORCEMENT.md`: optional setup for CI and hooks.
 
 Read these files only when needed. `SKILL.md` is the operating contract; the support files are progressive resources.
@@ -83,7 +84,8 @@ Triage decides IF documentation is due; this table decides WHICH document each e
 | `strategic/architecture.md`, `strategic/existing_features.md` | Bootstrap; update at closure when the knowledge catalog actually changed. | 1 / 5 |
 | `vision/project_vision.md`, `roadmap.md`, `principles.md` | Bootstrap as `Status: DRAFT`; promoted to APPROVED only by explicit user confirmation. | 1 / 2 |
 | `topics/<slug>.md` | A placement verdict creates it (MISSING/INADEQUATE-child, `taxonomy.md`); reconciliation updates its claim rows. One node per topic — a similar-but-distinct concept is a sibling with `related:` + a written distinction, never a merge and never a duplicate. Merged/renamed nodes become tombstones (`status: SUPERSEDED` + `redirect_to:`), never deleted. | 4 |
-| `corpus/given/*` + sidecar | A source arrives: verbatim copy, content-addressed, sidecar with digest/date/`supersedes:`; non-text originals also get their stored canonical extraction (`distillation.md` §1). Never edited after ingest — the digest check is what enforces it. | 4 |
+| a KB bundle (`export`) | Knowledge must leave this project. Export is L1 — it writes nothing into the corpus. **Importing one is L3**: a source enters the corpus and nodes are created, and a bundle is external input, so never L1 whatever its size (`portability.md`). | — |
+| `corpus/given/*` + sidecar | A source arrives: it becomes a content-addressed artifact with a sidecar carrying digest/date/`supersedes:`. A text source is copied verbatim. A non-text source yields its stored canonical extraction — copied **beside** the original when that is small enough to keep, or **instead of it** on a large binary corpus, where the original stays where it lives and is recorded as `original_path:`/`original_sha256:` (`distillation.md` §1, which owns this rule). Never edited after ingest — the digest check on whatever `given/` holds is what enforces it. | 4 |
 | `corpus/notes/*` | Something is said (`origin: elicited`), synthesised (`derived_from:`), or ruled (`basis:`). A note with none of the three is refused by the validator. | 4 / 5 |
 | `INDEX.md`, `reference/INDEX.md`, `topics/INDEX.md`, `corpus/INDEX.md` | Regenerated by `sdlc_check.py index` at closure — never by hand; `validate` fails on a hand-edited one. | 5 |
 

package/skills/kb-agentic-skill/distillation.md

@@ -69,7 +69,7 @@ Claims live in the owning topic's `## Claims` table (`templates.md` has the temp
   `p=<n>@<start>-<end>` (character offsets into page n of the stored extraction),
   `L<a>-<b>` (line files), `Sheet<s>!<cell>`. The span must exist — the validator opens
   the file and checks.
-- **prov** — `GIVEN | ELICITED | DERIVED | RULING`. Information for whoever resolves a
+- **prov** — `GIVEN | ELICITED | DERIVED | RULING | IMPORTED`. `IMPORTED` is a ruling that came from another project (`portability.md`): it keeps its text and original `basis:`, its note must say `imported_from:`, and it may not supersede a local row until you re-ratify it. Information for whoever resolves a
   conflict; never a rank.
 - **state** — `OK`, `CONTESTED <ids>`, `SUPERSEDED <id>` (`reconciliation.md` owns the
   transitions).

package/skills/kb-agentic-skill/portability.md

@@ -0,0 +1,125 @@
+# Portability — carrying knowledge between projects
+
+**For whom**: the agent moving a subgraph out of one project or into another.
+**Answers**: "what travels, what refuses to travel, and what an import may decide".
+**Does not answer**: where a claim's concept belongs (`taxonomy.md` — import *uses* that
+pass, it does not replace it) or how a disagreement is settled (`reconciliation.md`).
+
+## 0. The two commands, and what to tell the user
+
+A bundle is a **folder**, not an archive. Nothing here compresses or unpacks anything:
+the user moves the folder however they already move folders.
+
+**Sending side** — run from the project that owns the knowledge:
+
+```
+sdlc_check.py export --out ../kb-bundle                    # the whole KB
+sdlc_check.py export --out ../kb-bundle --topics pricing,licensing
+```
+
+Write it **outside the docs root**. A bundle sitting inside `ai_docs/` is a second copy
+of topics and corpus files in the tree the validator walks, and that confusion is free
+to avoid.
+
+**Receiving side** — run from the project that is to gain it:
+
+```
+sdlc_check.py import ../kb-bundle --dry-run     # see what would land
+sdlc_check.py import ../kb-bundle
+sdlc_check.py check                             # always, right after
+```
+
+**What to say to the user, in their words.** Say these four things and stop:
+
+1. *"I've written the bundle to `<path>`. It's a folder — move it to the other project
+   however you like."*
+2. *"It carries the source documents too, not just the notes, so it is not small. That is
+   the point: over there the claims can still be traced back to the page they came from."*
+3. After importing: *"Nothing was overwritten. Anything already there stayed as it was"* —
+   and, if a topic was skipped, *"a topic with the same name already exists; I have not
+   merged them, because they may not be the same subject. Do you want me to look?"*
+4. If an imported ruling arrived: *"one decision came from the other project. I have kept
+   it, marked as theirs, and it cannot settle anything here until you confirm it."*
+
+Do not explain the closure, the id hashing or the provenance model unless asked. The
+user asked to move their knowledge, not to learn how it is stored.
+
+## 1. What a bundle is
+
+A directory mirroring the docs-root layout:
+
+```
+<bundle>/
+  MANIFEST.md            kb_bundle: 1, source_project, topics, per-artifact sha256
+  topics/<slug>.md
+  corpus/given/<name>    + <name>.meta.md   (+ the .txt extraction, when there is one)
+  corpus/notes/<name>.md
+```
+
+The layout is mirrored **on purpose**. Claim `source` cells are docs-root-relative, so
+nothing is rewritten on import — and because `kb_claim_id` hashes
+`path#locator#qty` with the text excluded, the same artifact cited at the same span
+mints **the same id in every project**. De-duplication is therefore mechanical, not a
+judgement call, and importing the same bundle twice is a provable no-op.
+
+## 2. Export is a closure, not a selection
+
+You choose topics; the export decides what must travel with them.
+
+- **Every artifact a selected claim cites**, plus its sidecar and its stored extraction.
+  A claim whose source cannot be reopened is model knowledge arriving by another route —
+  the validator would reject it in the target, and correctly.
+- **Every row a `CONTESTED` row points at.** The symmetry check refuses a set that lost
+  half its members, so a partial export ships a tree that cannot pass its own checks.
+  When a partner row lives in an unselected topic, that topic is **added and reported** —
+  never dropped, never silently.
+
+If a conflict partner resolves to no row at all, the export **refuses**: exporting a
+broken set is worse than exporting nothing.
+
+## 3. Import is additive, and decides nothing
+
+`import` writes files. It does not place concepts, merge bodies, or settle disagreements.
+
+- **Never overwrites a topic.** A slug that already exists is reported and skipped: two
+  projects using the word `pricing` may mean two different things, and that judgement is
+  the placement pass's (`taxonomy.md`, five verdicts, `owns:` against double placement).
+- **Never deletes.** The doctrine is tombstones over deletion; an additive import has no
+  business removing anything.
+- **All or nothing.** The whole plan is computed before a byte is written. An import that
+  half-applies leaves a tree whose checks fail and whose owner cannot tell what landed.
+
+It refuses on: a missing or unmarked `MANIFEST.md`; a path that escapes the docs root; an
+artifact whose name matches an existing one **with different bytes** (content-addressed
+names must mean equal content — a mismatch means one of the two is lying about its
+origin); an incomplete conflict set; a dangling `supersedes:`.
+
+After importing, run `check`. The import is deliberately not a validator.
+
+## 4. Knowledge crosses; authority does not
+
+`RULING` means *the fact you know and the corpus does not*, with a `basis:` you gave. It
+is the only thing that settles a `CONTESTED` set. A ruling from another project carries
+another owner's decision, and importing it unchanged would make that decision binding
+here without anyone here granting it — the machine deciding, which reconciliation
+refuses everywhere else.
+
+So an imported ruling arrives as **`prov: IMPORTED`** (owner ruling, 2026-08-03):
+
+- its text, span and original `basis:` travel **verbatim** — the knowledge is not lost,
+  and pretending it is a `DERIVED` synthesis would make the row lie about where it came
+  from;
+- its note carries `imported_from:`, and the validator refuses an `IMPORTED` row without
+  it: unnamed, the class says nothing and the row is a `RULING` with the label filed off;
+- **it cannot supersede a local row.** The validator errors on `SUPERSEDED <id>` when
+  that id is `IMPORTED`.
+
+**Re-ratification** is one act: read it, write your own note with your own `basis:`, and
+set the row's `prov` to `RULING`. That is you deciding, which is the only thing that ever
+settles anything here.
+
+## 5. Triage
+
+Exporting is L1 — it writes nothing into the corpus and changes no knowledge. Importing
+is **L3**: a source enters the corpus and nodes are created, which is the L3 definition
+in Rule Zero, and the bundle is external input, which is never L1 whatever its size.

package/skills/kb-agentic-skill/reconciliation.md

@@ -76,4 +76,19 @@ Whole documents keep the family lifecycle: a superseding note or guide marks the
 `status: SUPERSEDED`; `supersedes:` in the new one's frontmatter links them. Claims and
 documents move independently — superseding a document does not silently resolve the
 claims extracted from it; the `corpus` check reports claims resting on superseded
-originals for re-verification.
+originals for re-verification.
+
+## Rulings that came from another project
+
+An `IMPORTED` row is a ruling made by the owner of a different project
+(`portability.md`). Knowledge crosses a project boundary; authority does not.
+
+- It keeps its text, its span and its original `basis:` verbatim — the knowledge is not
+  lost, and relabelling it `DERIVED` would make the row lie about its origin.
+- Its note must carry `imported_from:`. Unnamed, the class says nothing and the row is a
+  `RULING` with the label filed off; the validator refuses it.
+- **It cannot settle anything here.** `SUPERSEDED <id>` pointing at an `IMPORTED` row is
+  an error: nobody in this project granted that decision its authority.
+
+Re-ratification is one act, and it is you deciding: read it, write your own note with
+your own `basis:`, set `prov` to `RULING`.

package/skills/kb-agentic-skill/scripts/sdlc_check.py

@@ -62,12 +62,17 @@ sdlc_core.set_profile(
     unit_noun="topic",
     support_files=("templates.md", "taxonomy.md", "guides.md", "vision.md",
                    "distillation.md", "reconciliation.md", "elicitation.md",
-                   "review.md", "dispatch.md", "routing.md", "ENFORCEMENT.md"),
+                   "review.md", "dispatch.md", "routing.md", "portability.md",
+                   "ENFORCEMENT.md"),
     capabilities=(
         # spine
         "triage", "write_triggers", "workstream_registry", "vision_gate",
         "design_review_gate", "guide_router", "worktree_hygiene",
         # knowledge overlay
+        # `knowledge_portability` (F-030) is deliberately NOT declared: the
+        # capability vocabulary lives in the shared spine, and no shared test
+        # guards on portability, so adding a label there would mean editing
+        # sdlc_core.py in three distributions to buy nothing.
         "taxonomy_pass", "subagent_dispatch", "question_discipline",
     ),
     design_gate_between=("### 3. Request Analysis & Taxonomy Pass",
@@ -80,7 +85,7 @@ sdlc_core.set_profile(
 
 CLAIM_COLUMNS = ("id", "claim", "valid", "qty", "about", "source", "prov", "state")
 CLAIM_HEADING = "## Claims"
-PROVENANCES = ("GIVEN", "ELICITED", "DERIVED", "RULING")
+PROVENANCES = ("GIVEN", "ELICITED", "DERIVED", "RULING", "IMPORTED")
 SLUG_RE = re.compile(r"^[a-z0-9][a-z0-9-]{0,63}$")
 OWNS_RE = re.compile(r"^[a-z0-9][a-z0-9-]{0,63}/[a-z0-9][a-z0-9-]{0,63}$")
 DATE_RE = re.compile(r"^\d{4}-\d{2}-\d{2}$")
@@ -315,7 +320,7 @@ def kb_check_claims(root):
             prov = row["prov"]
             if prov not in PROVENANCES:
                 errors.append("%s: prov %r not in %s" % (where, prov, "/".join(PROVENANCES)))
-            elif prov in ("DERIVED", "RULING", "ELICITED"):
+            elif prov in ("DERIVED", "RULING", "ELICITED", "IMPORTED"):
                 meta = _note_frontmatter(root, first.rsplit("#", 1)[0])
                 if meta is None:
                     pass  # unresolvable source already reported
@@ -325,6 +330,13 @@ def kb_check_claims(root):
                 elif prov == "RULING" and not meta.get("basis"):
                     errors.append("%s: RULING note carries no 'basis:' — a preference "
                                   "is not a fact; no basis, no ruling" % where)
+                elif prov == "IMPORTED" and not meta.get("imported_from"):
+                    # F-030: IMPORTED exists so a foreign decision cannot pass for
+                    # a local one. Without the origin the class says nothing and
+                    # the row is a RULING with the label filed off.
+                    errors.append("%s: IMPORTED note carries no 'imported_from:' — "
+                                  "the class exists to name whose decision this "
+                                  "was; unnamed, it is a RULING in disguise" % where)
             # --- grammar cells ---
             try:
                 kb_parse_scope(row["valid"])
@@ -384,6 +396,18 @@ def kb_check_claims(root):
                                   "the check, it does not clean up" % (where, kind, t))
                     continue
                 orow, _ = other
+                if kind == "SUPERSEDED" and orow["prov"] == "IMPORTED":
+                    # F-030, owner ruling 2026-08-03: knowledge crosses a project
+                    # boundary, authority does not. An IMPORTED row carries another
+                    # owner's decision; letting it supersede a local row would make
+                    # that decision binding here without anyone here granting it.
+                    # Re-ratify first: write your own ruling note with your own
+                    # basis and flip the row to RULING.
+                    errors.append("%s: SUPERSEDED by %s, which is IMPORTED — a "
+                                  "foreign decision cannot settle a local row. "
+                                  "Re-ratify it (own note, own 'basis:', prov "
+                                  "RULING) or resolve this some other way"
+                                  % (where, t))
                 if kind == "CONTESTED":
                     if orow["state"].startswith("SUPERSEDED"):
                         errors.append("%s: CONTESTED points at SUPERSEDED row %s — "
@@ -734,10 +758,179 @@ def kb_sha256_bytes(path):
     return h.hexdigest()
 
 
+# ------------------------------------------------------- portability (F-030)
+# Export a subgraph WITH the bytes its claims cite; import it additively.
+#
+# The bundle mirrors the docs-root layout on purpose: claim `source` cells are
+# docs-root-relative, so nothing is rewritten on import and `kb_claim_id` --
+# sha256(path#locator#qty), text excluded -- mints the SAME id in both projects.
+# That is what makes de-duplication mechanical instead of a judgement call, and
+# it is why this feature is small.
+
+BUNDLE_MANIFEST = "MANIFEST.md"
+
+
+def kb_claim_sources(row):
+    """The docs-root-relative artifact paths a claim row cites (no locators)."""
+    out = []
+    for src in row["source"].split(";"):
+        src = src.strip()
+        if src and "#" in src:
+            out.append(src.rsplit("#", 1)[0])
+        elif src:
+            out.append(src)
+    return out
+
+
+def kb_collect_topics(docs):
+    """{slug: (path, text, rows)} for every topic node that parses."""
+    out = {}
+    tdir = docs / "topics"
+    if not tdir.is_dir():
+        return out
+    for p in sorted(tdir.glob("*.md")):
+        if p.name == "INDEX.md":
+            continue
+        text = sdlc_core.read_text(p)
+        meta = sdlc_core.load_frontmatter(text.splitlines()) or {}
+        rows, _ = kb_parse_claims(text)
+        out[(meta.get("topic") or p.stem).strip()] = (p, text, rows)
+    return out
+
+
+def kb_export_closure(docs, slugs):
+    """(topics, artifacts, added_for_conflicts, errors).
+
+    Closure in two directions, because a partial export produces a target whose
+    own checks fail:
+      * every artifact a selected claim cites travels with it -- a claim whose
+        source cannot be reopened is model knowledge arriving by another route;
+      * every row a CONTESTED row points at travels too, since the symmetry
+        check refuses a set that lost half its members. When such a row lives in
+        an unselected topic, that topic is ADDED and reported, never dropped.
+    """
+    all_topics = kb_collect_topics(docs)
+    errors = []
+    for s in slugs:
+        if s not in all_topics:
+            errors.append("no such topic: %s" % s)
+    if errors:
+        return {}, [], [], errors
+    selected = dict((s, all_topics[s]) for s in slugs)
+    # id -> slug, over the WHOLE graph, so a conflict partner is findable
+    owner_of = {}
+    for slug, (_p, _t, rows) in all_topics.items():
+        for r in rows:
+            if r["id"]:
+                owner_of[r["id"]] = slug
+    added = []
+    pending = list(selected)
+    while pending:
+        slug = pending.pop()
+        for r in selected[slug][2]:
+            m = re.match(r"^(CONTESTED|SUPERSEDED) ([0-9a-f, ]+)$", r["state"].strip())
+            if not m:
+                continue
+            for ref in [x.strip() for x in m.group(2).split(",") if x.strip()]:
+                other = owner_of.get(ref)
+                if other is None:
+                    errors.append("claim %s in topic '%s' points at id %s, which "
+                                  "no topic owns: export would carry a broken set"
+                                  % (r["id"] or "(no id)", slug, ref))
+                elif other not in selected:
+                    selected[other] = all_topics[other]
+                    added.append(other)
+                    pending.append(other)
+    artifacts = []
+    seen = set()
+    for slug, (_p, _t, rows) in sorted(selected.items()):
+        for r in rows:
+            for rel in kb_claim_sources(r):
+                for cand in (rel, rel + ".meta.md",
+                             rel[:-len(Path(rel).suffix)] + ".txt" if Path(rel).suffix else rel):
+                    if cand in seen:
+                        continue
+                    if (docs / cand).is_file():
+                        seen.add(cand)
+                        artifacts.append(cand)
+    return selected, artifacts, added, errors
+
+
+def kb_bundle_write(docs, out, selected, artifacts, project):
+    """Write the bundle. Mirrors the docs-root layout; no path is rewritten."""
+    out.mkdir(parents=True, exist_ok=True)
+    (out / "topics").mkdir(exist_ok=True)
+    for slug, (p, text, _rows) in sorted(selected.items()):
+        (out / "topics" / p.name).write_text(text, encoding="utf-8")
+    for rel in artifacts:
+        dst = out / rel
+        dst.parent.mkdir(parents=True, exist_ok=True)
+        dst.write_bytes((docs / rel).read_bytes())
+    lines = ["---", "kb_bundle: 1", "source_project: %s" % project,
+             "topics: [%s]" % ", ".join(sorted(selected)),
+             "artifacts: %d" % len(artifacts), "---",
+             "# KB bundle", "",
+             "Import with `sdlc_check.py import <this directory>`. Additive: it "
+             "never overwrites a node and never deletes anything.", ""]
+    for rel in artifacts:
+        lines.append("- `%s` sha256:%s" % (rel, kb_sha256_bytes(docs / rel)))
+    (out / BUNDLE_MANIFEST).write_text("\n".join(lines) + "\n", encoding="utf-8")
+
+
+def kb_import_plan(bundle, docs):
+    """(writes, skipped_topics, dedup, errors) -- computed BEFORE anything is
+    written, because an import that half-applies leaves a tree whose checks fail
+    and whose owner cannot tell what landed."""
+    errors, writes, skipped, dedup = [], [], [], []
+    man = bundle / BUNDLE_MANIFEST
+    if not man.is_file():
+        return [], [], [], ["not a kb bundle: no %s in %s" % (BUNDLE_MANIFEST, bundle)]
+    meta = sdlc_core.load_frontmatter(sdlc_core.read_text(man).splitlines()) or {}
+    if str(meta.get("kb_bundle", "")).strip() != "1":
+        return [], [], [], ["%s carries no 'kb_bundle: 1'" % BUNDLE_MANIFEST]
+
+    known_ids = set()
+    target = kb_collect_topics(docs)
+    for _slug, (_p, _t, rows) in target.items():
+        for r in rows:
+            if r["id"]:
+                known_ids.add(r["id"])
+
+    for p in sorted(bundle.rglob("*")):
+        if not p.is_file() or p.name == BUNDLE_MANIFEST:
+            continue
+        rel = p.relative_to(bundle).as_posix()
+        dst = sdlc_core.confine_under(docs, rel)
+        if dst is None:
+            errors.append("bundle entry %r escapes the docs root — refusing the "
+                          "whole import, not just this file" % rel)
+            continue
+        if dst.is_file() and not rel.startswith("topics/"):
+            if kb_sha256_bytes(dst) != kb_sha256_bytes(p):
+                errors.append("%s exists with different bytes (target %s… vs "
+                              "bundle %s…): content-addressed names must mean "
+                              "equal content" % (rel, kb_sha256_bytes(dst)[:8],
+                                                 kb_sha256_bytes(p)[:8]))
+            continue
+        if rel.startswith("topics/") and dst.is_file():
+            skipped.append(rel)
+            continue
+        writes.append((rel, p, dst))
+
+    for rel, p, _dst in writes:
+        if not rel.startswith("topics/"):
+            continue
+        rows, _ = kb_parse_claims(sdlc_core.read_text(p))
+        for r in rows:
+            if r["id"] and r["id"] in known_ids:
+                dedup.append(r["id"])
+    return writes, skipped, dedup, errors
+
+
 # ------------------------------------------------------------------ commands
 
 INTERCEPTED = {"index", "validate", "check", "graph", "corpus", "claim-id",
-               "anchor"}
+               "anchor", "export", "import"}
 
 
 def _kb_root(args):
@@ -859,10 +1052,27 @@ def kb_cmd_claim_id(args):
 
 
 def kb_cmd_anchor(args):
-    """Prose citation -> a verified span. The half `claim-id` never had."""
+    """Prose citation -> a verified span. The half `claim-id` never had.
+
+    The path may be given as it appears in a claim's `source` cell
+    (`corpus/given/x-ab12cd34.txt`): when it does not resolve from the current
+    directory it is retried under the docs root, so the command works from
+    anywhere in the project instead of only from inside `ai_docs/`. Reported
+    from the field as an asymmetry with `graph`/`corpus`/`check`, which take
+    `--root`; those scan a tree, this one takes a path, and the fix is to make
+    the path resolve rather than to document where to stand."""
     p = Path(args.path)
     if not p.is_file():
-        print("[ERROR] no such file: %s" % p)
+        try:
+            _, docs = _kb_root(args)
+            if (docs / args.path).is_file():
+                p = docs / args.path
+        except sdlc_core.AmbiguousDocsRoot:
+            pass
+    if not p.is_file():
+        print("[ERROR] no such file: %s" % args.path)
+        print("        looked from the current directory and under the docs "
+              "root; give the path as the claim's `source` cell carries it.")
         return 2
     hits = kb_resolve_anchor(p, args.phrase, ignore_case=args.ignore_case,
                              page=args.page)
@@ -883,6 +1093,62 @@ def kb_cmd_anchor(args):
     return 0
 
 
+def kb_cmd_export(args):
+    root, docs = _kb_root(args)
+    slugs = ([s.strip() for s in args.topics.split(",") if s.strip()]
+             if args.topics else sorted(kb_collect_topics(docs)))
+    if not slugs:
+        print("[ERROR] no topics to export")
+        return 2
+    selected, artifacts, added, errors = kb_export_closure(docs, slugs)
+    for e in errors:
+        print("[ERROR] %s" % e)
+    if errors:
+        return 1
+    out = Path(args.out)
+    kb_bundle_write(docs, out, selected, artifacts, root.name)
+    print("[ok] bundle written: %s" % out)
+    print("     topics: %d, artifacts: %d" % (len(selected), len(artifacts)))
+    if added:
+        # never silent: a set that grew is a fact about the export, and the
+        # alternative -- dropping the partner rows -- ships a broken tree.
+        print("     +%d topic(s) added to keep conflict sets whole: %s"
+              % (len(added), ", ".join(sorted(added))))
+    return 0
+
+
+def kb_cmd_import(args):
+    _root, docs = _kb_root(args)
+    bundle = Path(args.bundle)
+    if not bundle.is_dir():
+        print("[ERROR] no such bundle directory: %s" % bundle)
+        return 2
+    writes, skipped, dedup, errors = kb_import_plan(bundle, docs)
+    for e in errors:
+        print("[ERROR] %s" % e)
+    if errors:
+        print("[ERROR] nothing was written: an import that half-applies leaves a "
+              "tree whose checks fail and whose owner cannot tell what landed.")
+        return 1
+    if args.dry_run:
+        print("[ok] dry run: %d file(s) would be written" % len(writes))
+    else:
+        for _rel, src, dst in writes:
+            dst.parent.mkdir(parents=True, exist_ok=True)
+            dst.write_bytes(src.read_bytes())
+        print("[ok] imported %d file(s) into %s" % (len(writes), docs))
+    if dedup:
+        print("     %d claim(s) already present, by id — the same artifact cited "
+              "at the same span mints the same id in any project" % len(dedup))
+    for rel in skipped:
+        print("[note] %s already exists: NOT overwritten. Run the placement pass "
+              "(taxonomy.md) and merge by hand — an import never decides that."
+              % rel)
+    print("[note] re-run 'sdlc_check.py check' now: the import is additive, and "
+          "an imported RULING stays IMPORTED until you re-ratify it.")
+    return 0
+
+
 def kb_cmd_help():
     """The spine's usage, then the overlay's own commands.
 
@@ -902,6 +1168,8 @@ knowledge overlay (kb-agentic) -- also available:
   corpus                      corpus integrity: digests, supersession, notes
   claim-id <path> <locator>   compute a claim id (--fill to fill a whole table)
   anchor <path> <phrase>      resolve a phrase to a verified locator span
+  export --out <dir>          bundle a subgraph WITH the bytes its claims cite
+  import <dir>                merge a bundle in additively (never overwrites)
 
   index / validate / check    the spine's behaviour PLUS the claim ledger and
                               the topic graph""")
@@ -940,14 +1208,30 @@ def main(argv=None):
     p = sub.add_parser("anchor")
     p.add_argument("path")
     p.add_argument("phrase")
+    p.add_argument("--root")
+    p.add_argument("--docs-dir")
     p.add_argument("--page", type=int)
     p.add_argument("--ignore-case", action="store_true")
     p.add_argument("--all", action="store_true")
+    p = sub.add_parser("export")
+    p.add_argument("--out", required=True)
+    p.add_argument("--topics")
+    p.add_argument("--root")
+    p.add_argument("--docs-dir")
+    p = sub.add_parser("import")
+    p.add_argument("bundle")
+    p.add_argument("--dry-run", action="store_true")
+    p.add_argument("--root")
+    p.add_argument("--docs-dir")
     args = ap.parse_args(argv)
     if args.cmd == "claim-id":
         return kb_cmd_claim_id(args)
     if args.cmd == "anchor":
         return kb_cmd_anchor(args)
+    if args.cmd == "export":
+        return kb_cmd_export(args)
+    if args.cmd == "import":
+        return kb_cmd_import(args)
     try:
         root, docs = _kb_root(args)
     except sdlc_core.AmbiguousDocsRoot as e: