@antoneeo/kb-agentic-skill 1.28.0 → 1.32.0

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

@@ -39,7 +39,8 @@ sdlc_check.py check                             # always, right after
    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."*
+   it, marked as theirs, and it cannot settle anything here until you confirm it. The
+   question it had closed is open again here, with their decision beside the sources."*
 
 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.
@@ -73,13 +74,23 @@ You choose topics; the export decides what must travel with them.
   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.
+- **Not the `not-yet-honored-by` markers.** They describe this project's code, so the export drops them and says so, without a number.
+- **Not the declarations.** A `DECLARED` row is this project's commitment to its own
+  recipient; carried elsewhere it would read as the importer's. The export leaves the
+  rows and the artifacts only they cite behind and says so in one line, without a
+  number. Nothing else is lost: no other row may point at a declaration, and the export
+  refuses one that does (run `check`).
 
 If a conflict partner resolves to no row at all, the export **refuses**: exporting a
 broken set is worse than exporting nothing.
 
+A withdrawn artifact (`distillation.md` §1) never travels: it has no bytes, and its
+tombstone sidecar stays home.
+
 ## 3. Import is additive, and decides nothing
 
-`import` writes files. It does not place concepts, merge bodies, or settle disagreements.
+`import` writes files. It does not place concepts, merge bodies, or settle disagreements —
+and it refuses to let the bundle settle them either: a ruling arrives foreign (§4).
 
 - **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
@@ -92,7 +103,12 @@ broken set is worse than exporting nothing.
 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:`.
+origin); an incomplete conflict set — a `CONTESTED` or `SUPERSEDED` pointer that would
+resolve to no row, or to a row of this project that does not name it back (an import
+never edits an existing topic); a row settled by a ruling the import does not write, or
+by a row this project holds as `IMPORTED`; a ruling it cannot carry foreign (§4); a
+`DECLARED` row (an export never ships one, so the bundle was edited by hand). Each
+refusal names the row and writes nothing.
 
 After importing, run `check`. The import is deliberately not a validator.
 
@@ -104,22 +120,76 @@ another owner's decision, and importing it unchanged would make that decision bi
 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.
+So `import` makes every `RULING` row of a topic it writes arrive as **`prov: IMPORTED`**
+(owner rulings 2026-08-03 and 2026-10-23):
+
+- **its note arrives as a renamed copy**, `corpus/notes/imported_<source project>_<name>`,
+  whose frontmatter adds `imported_from: <source project> — <original path>` and reads
+  `origin: imported`. Its text 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. The note is never edited under its own name: a line inserted into
+  it would move the line every locator cites. The row cites the copy at the same text
+  (its locator and id move with it), and a bundle note `derived_from:` the ruling names
+  the copy. The original name is never written, so a row copied by hand out of a skipped
+  topic cannot cite a foreign note as local;
+- **the question it had closed reopens.** The rows it superseded and the ruling itself
+  arrive as one `CONTESTED` set; a ruling already contested with a newer source keeps
+  that partner, one that superseded nothing arrives `OK`;
+- the validator refuses an `IMPORTED` row whose note lacks `imported_from:` (unnamed,
+  the class says nothing), a `SUPERSEDED <id>` pointing at an `IMPORTED` row, and a
+  `RULING` row on a note that names a foreign origin.
+
+**Ratification** is the ordinary ruling of `reconciliation.md`, and it is you deciding,
+which is the only thing that ever settles anything here: write your own note with your
+own `basis:`, add a `RULING` row on it, and mark every row `CONTESTED` with the imported
+one — following the sets transitively — `SUPERSEDED <your id>`, the `IMPORTED` row
+included. Relabelling the `IMPORTED` row `RULING` is refused: another project's note
+cannot carry your decision.
+
+Any bundle note that declares a `basis:` lands this way, renamed, even when its ruling row
+does not travel with it — otherwise it would land first under its own name and a later
+import of its ruling would find it there. A ruling `import` cannot carry this way is
+refused, never copied: one not resting on a note cited by line, on a note with no
+frontmatter, or on a note that already names a foreign origin (the source relabelled an
+imported row); a row superseded both by a ruling and by a row that is not one; a ruling
+another row superseded while rows still depend on it. A tree imported before this
+conversion existed (≤ kb 1.31.0) holds the foreign ruling as `RULING` on its original
+note: delete the imported topic and its files and import again, or convert it by hand as
+above. The origin is named after the exporting folder (`source_project`), so two clones
+of one project in differently named folders name it differently.
 
 ## 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.
+Adoption (§6) is **L3** for the same reason.
+
+## 6. Adopting kb-agentic on an existing `ai_docs/`
+
+A project that used agentic-sdlc first has distilled its documents into
+`source_kind: document` guides whose sources are snapshots in `reference/.sources/`.
+With a corpus, a document's text has one home, `corpus/given/` (`distillation.md` §1).
+Moving it is one L3 unit:
+
+1. **Inventory.** `sdlc_check.py adopt` lists each document guide, where its source is
+   (`.sources/` snapshot, already in `given/`, elsewhere, missing), a `given/` artifact
+   holding the same text, and credential-shaped lines. It writes nothing; there is no
+   `--apply`, because steps 2 and 3 are judgements.
+2. **Choose the source, per guide.** The original, when it is reachable and is the
+   version the guide was distilled from — it is complete. Otherwise the snapshot, which
+   is a verbatim excerpt: its sidecar says so in its prose line ("verbatim excerpt of
+   <original>, selected for <guide> on <date>"), with `original_ref:` or
+   `original_path:` when known, and what the excerpt left out is a `gaps:` entry on the
+   topic, never assumed read.
+3. **Redact** (`distillation.md` §1), then store the artifact under its content-addressed
+   name, with its sidecar.
+4. **Re-point the guide**: `distilled_from:`, `source_hash` (the line-ending-normalized
+   digest), and its markers now name the artifact. The guide keeps its name.
+5. **Delete the snapshot**, then run `check` and `stale`.
+
+Past decisions are not rewritten: analyses, ADRs and diaries that cite the guide keep
+citing it, and a citation of the old snapshot path resolves in git history. A secret
+already committed in a snapshot stays in that history — say so to the user; purging it
+is theirs. Extracting claims from the adopted artifacts is an ordinary ingestion,
+afterwards.

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

@@ -24,6 +24,15 @@ Subject-sameness is semantic judgement; no query performs it. Classify:
 | **coexistence** | contradictory only if scopes overlapped — and by the half-open rule they do not | both rows stay `OK`. "12k until March" and "15k from March" are two truths, not a conflict |
 | **conflict** | contradictory, scopes overlap | **every** row in the set becomes `CONTESTED` listing all counterparts. Nothing is picked |
 
+**A declaration is not a source.** A `DECLARED` row (`distillation.md` §1: what this
+project sent) never joins the five outcomes with a fact: it never corroborates a row,
+never refines or supersedes one, never contests one. Against the ledger it is either
+consistent (`OK`) or it **diverges**: its assertion contradicts a non-superseded,
+non-DECLARED row, scopes overlapping → the DECLARED row alone becomes
+`DIVERGES <id>[, ..]`; the ledger row is not touched, because our own wrong statement
+puts nothing about the product in doubt. Two declarations that contradict each other
+are `CONTESTED` — both are still held by their recipients.
+
 The machine then verifies (the `graph` check): ids recompute, sources resolve and their
 spans exist, `CONTESTED` is **symmetric** (editing one cell to `OK` fails the check —
 the cheapest laundering), a `CONTESTED` pointer at a `SUPERSEDED` row is an error,
@@ -73,8 +82,13 @@ premise: signed amendments arrive later.
 | newer source vs a ruling | new set {new row, ruling row}; escalation shows the `basis:` |
 | member refined | the refining row inherits the member's contested relations (re-judged); counterparts rewritten to the new id |
 | corroboration of a contested member | source appended; the set untouched — more evidence is not new information, and the escalation form shows source counts |
+| a declaration contradicts the ledger | the DECLARED row → `DIVERGES <ledger ids>`; the ledger rows stay as they are; escalation names it |
+| a new send corrects it | the new DECLARED row; the divergent one → `SUPERSEDED <new-id>` (a declaration is superseded only by a later declaration) |
+| a ruling changes the decision | the ledger row → `SUPERSEDED <ruling-id>`; `check` then refuses the stale `DIVERGES` until the declaration is re-judged against the ruling: `OK` if it now agrees, `DIVERGES <ruling-id>` if not |
 | bundled row split (`distillation.md` §3) | N atomic rows `OK`, each on its narrowed span; the bundle → `SUPERSEDED <id1>[, <id2> ..]`, text intact; contested relations re-judged per successor |
 
+A superseded row keeps its `not-yet-honored-by` marker with its text. Copy the marker to each successor that still states behavior the code does not have; the analysis or shadow citing the predecessor's id satisfies the successor.
+
 ## 3-bis. Splitting a bundled row
 
 A row carrying more than one assertion (`distillation.md` §3 — atomic as provenance,
@@ -101,7 +115,11 @@ record like any claim-table edit.
 Escalations are presented **once, at the end of a run** — the pipeline never stops
 mid-ingest to ask. Each escalation names: the claims in the set, each one's source
 (reopenable), date and provenance, and one line on why the machine cannot decide
-("same subject, overlapping validity, GIVEN vs GIVEN, no newer source"). **A question
+("same subject, overlapping validity, GIVEN vs GIVEN, no newer source"). A divergence
+is escalated the same way, naming the recipient and the day it was sent: the
+practitioner corrects it with a new send or changes the decision. One limit stated
+out loud: `DIVERGES` is one-way, so unlike `CONTESTED` a hand edit back to `OK` has
+no counterpart to fail on — the diff review is what catches it. **A question
 that cannot fill this form is not askable** — it is the symptom that the answer is in
 the corpus and was not searched. Generic confirmations are not questions.
 
@@ -120,10 +138,15 @@ An `IMPORTED` row is a ruling made by the owner of a different project
 
 - 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`.
+- It rests on a renamed copy of its note (`imported_<project>_<name>`) that carries
+  `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.** `import` reopens the set it had settled: its former
+  members and the ruling arrive `CONTESTED` with each other. `SUPERSEDED <id>` pointing at
+  an `IMPORTED` row is an error: nobody in this project granted that decision its
+  authority.
+
+Ratification is the ruling procedure above, and it is you deciding: your own note with
+your own `basis:`, a `RULING` row on it, and every row `CONTESTED` with the imported one —
+transitively, when it sits in more than one set — `SUPERSEDED <your id>`, the imported row
+included. A `RULING` on a note that names a foreign origin is refused.

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

@@ -187,7 +187,10 @@ can block forever gets removed. **Log one row per completed review, PASS or FAIL
 logging only passes would erase exactly that evidence. The row goes in
 `ai_docs/audit/reviews/REVIEW_LOG.md` (create it if absent — `templates.md`):
 `| date | doc_key | tier | model | reviewer | findings_raised | findings_real | verdict | revise_rounds |`,
-with `tier` = `design` or `closure` in Standalone. **`model` records the capability
+with `tier` = `design` or `closure` in Standalone. In the code lens, a wrong behaviour
+the owner reports in a merged L3 change is one row too, tier `post-merge`, `model`
+`none (owner report)`, reviewer `owner`, the owner quoted in the notes: a defect
+record, not a review, so `benefit` keeps it out of every review figure. **`model` records the capability
 tier that actually ran** — `deep`, `light`, `economy`, `single (client exposes no
 choice)`, `below floor: <reason>`, or `none (not due)` on a NOT DUE row — never a provider name in doctrine (a project
 may of course write its own model names in its own log). Without it the floor above
@@ -285,6 +288,11 @@ The binding inputs, by review type:
   clause reads both), and the **probe harness** (`ai_docs/solutions/harness_[feature]/`).
   Hand these *in addition to* the design artifact — the reviewer checks the artifact
   **against** them, not only for internal consistency.
+- **The constraint view comes last.** Where the ANALYSIS carries ids, the reviewer
+  derives the callers and behaviours first, then compares with
+  `sdlc_check.py constraints --unit <id>`: a constraint the design states and the
+  diff breaks is a finding. The view never replaces the ANALYSIS or the diff in the
+  request.
 - **For a closure review, the diff and the test evidence**: the run output that
   backs every completion claim, dated after the final relevant change.
 - **For a design or closure review of an L3/E3 unit, the request record**

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

@@ -92,6 +92,10 @@ Run the steps in order. Stop at the first one that decides.
 | "research sources and teach a newcomer a topic" | purpose: teaching → course | never reached | never reached | **course** |
 | "ingest these manuals, then create a course" | split: corpus = supplied docs; training = teaching | never reached | never reached | **knowledge** for ingestion; **course** for training |
 | "write sales copy and an onboarding course" | split: persuasion and teaching | never reached | never reached | **marketing** for copy; **course** for training |
+| "write the interface spec of our service for another team" (kept and versioned with the repo) | code | repo's own doc set → code | not build-consumed → no flip | **code** |
+| "write the requirements another team must build, from their documents and our notes" | supplied docs → knowledge | never reached | never reached | **knowledge** |
+| "the vendor spec changed: update the guide distilled from it" | split (step 4): guide = supplied docs; any code change the new spec requires = this repo | never reached | never reached | **knowledge** for re-distilling the guide; **code** for the code change, citing the guide |
+| "the code and the supplied spec diverge" | split (step 4): changing the code = this repo; correcting the distillation = supplied docs | never reached | never reached | **code** if the code is wrong; **knowledge** if the distillation is — which one is wrong is the owner's call, not the router's |
 
 ## 3. Acting on the verdict
 

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

@@ -33,6 +33,7 @@ import re
 import shutil
 import subprocess
 import sys
+import zipfile
 import unicodedata
 import urllib.parse
 from datetime import datetime
@@ -614,6 +615,11 @@ class Grounds:
             return [{"kind": "untraceable", "path": rel}]
         seen = seen | {rel}
         if rel.startswith("corpus/given/"):
+            # F-084: a document this project SENT is our own declaration, not
+            # ground for a fact about the product.
+            side = self._meta(rel + ".meta.md")
+            if _v(side, "provenance").upper() == "DECLARED":
+                return [{"kind": "declared", "path": rel}]
             return [{"kind": "document", "path": rel}]
         if not _inside(self.docs, rel) or not (self.docs / rel).is_file():
             return [{"kind": "untraceable", "path": rel}]
@@ -642,6 +648,8 @@ def ground_class(leaves):
         return "statement"
     if "untraceable" in kinds:
         return "untraceable"
+    if "declared" in kinds:
+        return "declared"
     if "kb" in kinds:
         return "imported"
     return "documents"
@@ -706,12 +714,15 @@ def build_kb(docs):
             kind, rest = _kind(r)
             f = {"text": r["claim"], "valid": r["valid"], "qty": r["qty"], "about": r["about"],
                  "origin": (r["prov"] or "").strip().lower(), "topic": slug,
-                 "state": {"SUPERSEDED": "superseded", "CONTESTED": "contested"}.get(kind, "ok")}
+                 "state": {"SUPERSEDED": "superseded", "CONTESTED": "contested",
+                           "DIVERGES": "diverges"}.get(kind, "ok")}
             if kind == "SUPERSEDED":
                 f["successors"] = _ids(rest)
                 f["chain_ends"] = chain_ends(r["id"], by_id)
             if kind == "CONTESTED":
                 f["with"] = _ids(rest)
+            if kind == "DIVERGES":
+                f["diverges_from"] = _ids(rest)
             srcs = []
             for src in r["source"].split(";"):
                 src = src.strip()
@@ -767,6 +778,8 @@ def build_sources(docs, rows_of):
         name = mp.name[:-len(".meta.md")]
         t = _text(mp) or ""
         meta = sdlc_core.load_frontmatter(t.splitlines()) or {}
+        if knowledge.kb_is_tombstone(meta):
+            continue  # withdrawn: no bytes to show; corpus/INDEX.md keeps the row
         through = _v(meta, "extracted_through")
         parsed = knowledge.kb_parse_extracted_through(through) if through else None
         if not through:
@@ -1221,7 +1234,14 @@ def chronology(docs, pages):
         text = _text(p)
         # a shadow mirror is not an analysis to `validate` (list_analyses): not here either
         if text is not None and not sdlc_core.is_shadow(p, (text.splitlines() or [""])[0]):
+            # a Diary label ("closed", "Approved (R5)") names no unit: prefix the id, so
+            # the event reads on its own in the chronology (field case 2026-10-19)
+            uid = dict((k.lower(), v) for k, v in split_frontmatter(text)[0]).get("id", "").strip()
+            start = len(events)
             openers("solutions/" + p.name, "diary", sdlc_core.DIARY_SECTION)
+            if uid:
+                for e in events[start:]:
+                    e["label"] = "%s — %s" % (uid, e["label"])
     # spike outcomes: SPIKE_* in the code/kb/course lenses, RESEARCH_* in marketing
     for rel in sorted(["solutions/" + p.name for p in docs.glob("solutions/SPIKE_*.md")]
                       + ["spikes/" + p.name for p in docs.glob("spikes/RESEARCH_*.md")]):
@@ -1236,7 +1256,9 @@ def chronology(docs, pages):
     text = _text(docs / rel) if (docs / rel).is_file() else None
     if text is not None:
         for row in sdlc_core.parse_review_log(text)[0]:
-            add(row["date"], "review", "%s — %s: %s" % (
+            # F-085: a `post-merge` row is the owner's defect report, not a review
+            kind = "defect" if row["tier"].lower().startswith("post-merge") else "review"
+            add(row["date"], kind, "%s — %s: %s" % (
                 row["doc_key"], row["tier"], row["verdict"]), rel)
     for p in sorted(docs.glob("architecture/ADR_*.md")):
         rel = "architecture/" + p.name
@@ -1251,13 +1273,17 @@ def chronology(docs, pages):
             text = _text(p)
             if text is None:
                 continue
-            date = knowledge.frontmatter_date(
-                sdlc_core.load_frontmatter(text.splitlines()))
+            fm = sdlc_core.load_frontmatter(text.splitlines())
+            date = knowledge.frontmatter_date(fm)
             if not date:
                 continue
+            if kind == "source" and knowledge.kb_is_tombstone(fm):
+                continue
             if kind == "source":
                 name = p.name[:-len(suffix)]
-                add(date, kind, name, rel, source=name)
+                # F-084: a DECLARED sidecar's date is the day it was SENT
+                sent = _v(fm, "provenance").upper() == "DECLARED"
+                add(date, "sent" if sent else kind, name, rel, source=name)
             else:
                 add(date, kind, title_of(rel, text), rel)
     # Most recent first. Within one day a document's later entry is the more recent
@@ -1289,6 +1315,29 @@ def check_out(out, docs):
     return out
 
 
+def check_zip(target, docs, out):
+    """Where `--zip` may write: a .zip file outside the docs root and outside the site."""
+    target = target.resolve()
+    if target.suffix.lower() != ".zip":
+        raise SiteError("--zip %s must name a .zip file." % target)
+    for folder, what in ((docs.resolve(), "the docs root"), (out.resolve(), "the site folder")):
+        if target == folder or folder in target.parents:
+            raise SiteError("--zip %s is inside %s %s." % (target, what, folder))
+    if target.exists() and not target.is_file():
+        raise SiteError("--zip %s exists and is not a file." % target)
+    return target
+
+
+def write_zip(out, target):
+    """The site as one file to share. Entry names always use '/': an archive whose names
+    carry '\\' (Windows PowerShell 5.1 Compress-Archive) unpacks on Linux and macOS as
+    files named `data\\core.js`, and the page then finds no data (field case 2026-10-19)."""
+    with zipfile.ZipFile(str(target), "w", zipfile.ZIP_DEFLATED) as z:
+        for p in sorted(out.rglob("*")):
+            if p.is_file() and p.name != MARKER:
+                z.write(str(p), p.relative_to(out).as_posix())
+
+
 def write_site(out, core, pages, kb):
     out.mkdir(parents=True, exist_ok=True)
     for rel in PAGE_FILES + ("data",):
@@ -1324,6 +1373,30 @@ def git_ignored(project, out):
         return None
 
 
+def ensure_ignored(project, out):
+    """Add the site folder to the project's .gitignore when git does not ignore it, so the
+    site's copy of the documents is not committed. An entry already in the file is never
+    rewritten (git may ignore it elsewhere, or the user negated it on purpose). Returns the
+    line added, or None; False when the folder stays not ignored."""
+    if git_ignored(project, out) is not False:
+        return None
+    rel = out.resolve().relative_to(project.resolve()).as_posix()
+    entry = rel + "/"
+    gi = project / ".gitignore"
+    try:
+        raw = gi.read_bytes() if gi.is_file() else b""
+        text = raw.decode("utf-8")
+        if {rel, entry, "/" + rel, "/" + entry} & {l.strip() for l in text.splitlines()}:
+            return False
+        nl = "\r\n" if "\r\n" in text else "\n"
+        sep = nl if text and not text.endswith(("\n", "\r")) else ""
+        with open(str(gi), "ab") as f:
+            f.write((sep + entry + nl).encode("utf-8"))
+    except (OSError, UnicodeDecodeError):
+        return False
+    return entry
+
+
 def _shown(path, docs):
     try:
         return Path(path).relative_to(docs).as_posix()
@@ -1339,11 +1412,14 @@ def main(argv=None):
     ap.add_argument("--docs-dir", dest="docs_dir", help="docs root name (ai_docs or mkt_docs)")
     ap.add_argument("--out", help="output folder (default: <project>/%s)" % DEFAULT_OUT)
     ap.add_argument("--open", action="store_true", help="open the site in the browser")
+    ap.add_argument("--zip", metavar="FILE",
+                    help="also write the site as one .zip to share; it opens on any system")
     args = ap.parse_args(argv)
     del _UNREADABLE[:]
     try:
         project, docs, name = resolve_root(args)
         out = check_out(Path(args.out) if args.out else project / DEFAULT_OUT, docs)
+        target = check_zip(Path(args.zip), docs, out) if args.zip else None
     except SiteError as exc:
         print("[ERROR] %s" % exc)
         return 2
@@ -1366,9 +1442,16 @@ def main(argv=None):
         ", %d topics, %d facts" % (len(kb["order"]), len(kb["facts"])) if kb else "", docs))
     for path, exc in _UNREADABLE:
         print("[ERROR] unreadable: %s (%s)" % (_shown(path, docs), exc))
-    if git_ignored(project, out) is False:
+    added = ensure_ignored(project, out)
+    if added:
+        print("[ok] added %s to %s so the site's copy of your documents is not committed."
+              % (added, project / ".gitignore"))
+    elif added is False:
         print("[note] %s is not git-ignored: add it to .gitignore so the site's copy of "
               "your documents is not committed." % out)
+    if target:
+        write_zip(out, target)
+        print("[ok] docs site zipped: %s (unzip it and open index.html)" % target)
     if args.open:
         import webbrowser
         webbrowser.open((out / "index.html").as_uri())