Sync: local changes as of 2026-07-15T15:44:47+02:00

.agents/skills/ckb-export-okf/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: export-okf
+name: ckb-export-okf
 description: Export the local wiki/ knowledge base as an Open Knowledge Format (OKF) v0.1-conformant bundle at outputs/okf/, so any generic OKF tool can consume it. Use when the user asks to "export the wiki as OKF", "generate the OKF bundle", "export to OKF", "publish the OKF export", or "sync outputs/okf".
 ---
 

.agents/skills/ckb-export-starlight/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: export-starlight
+name: ckb-export-starlight
 description: Export the local wiki/ knowledge base into an Astro + Starlight-consumable form at outputs/starlight/, producing a human-readable documentation website. Use when the user asks to "export the wiki to Starlight", "generate the docs site", "export as Astro Starlight", "build a human-readable wiki site", or "publish the knowledge base as a website".
 ---
 
@@ -10,7 +10,7 @@ description: Export the local wiki/ knowledge base into an Astro + Starlight-con
 Regenerate `outputs/starlight/` from the current `wiki/` tree so it can be
 built and served as an Astro + Starlight documentation website — a
 human-readable, browsable version of this knowledge base (unlike
-`export-okf`, which targets machine/tool consumption). This is a one-way,
+`ckb-export-okf`, which targets machine/tool consumption). This is a one-way,
 on-demand export — `wiki/` stays the authoritative source; `outputs/starlight/`
 is always a derived artifact of it, never edited by hand and never fed back
 in.
@@ -143,5 +143,5 @@ The script prints, and you should summarize back to the user:
 - **A wiki page with no `tldr`:** `description` is simply omitted from
   that page's frontmatter — Starlight tolerates a missing description.
 - **A wiki page with no H1:** falls back to a slugified filename as the
-  title (e.g. `foo-bar.md` → "Foo Bar"), same fallback rule `export-okf`
+  title (e.g. `foo-bar.md` → "Foo Bar"), same fallback rule `ckb-export-okf`
   uses.

.agents/skills/ckb-init/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: cascade-kb-init
+name: ckb-init
 description: Bootstrap a brand-new Cascade Knowledge Base - the same directory structure, AGENTS.md/CLAUDE.md system prompt, and empty wiki/ scaffold as this project - inside a target folder (typically empty, or a new project that doesn't have one yet). Use when the user asks to "set up a new wiki like this one", "initialize a new cascade KB", "bootstrap a wiki here", "create a knowledge base with this schema", or calls it a "wiki initializer". Do not confuse with a generic `init` skill that documents an existing codebase - this one creates the Cascade KB pattern itself, empty, ready for its first ingest.
 ---
 
@@ -60,8 +60,8 @@ The bare scaffold (directory structure + `AGENTS.md`/`CLAUDE.md` + empty
 `wiki/` templates) is always included, and so is the reusable KB skill set
 - these operate purely on the `wiki/` structure, so they carry over
 cleanly and are part of "the schema" as far as this skill is concerned:
-`export-okf`, `export-starlight`, `sync-changes`, `extract-transcript`,
-`project-summary`. Don't ask about these - just include them.
+`ckb-export-okf`, `ckb-export-starlight`, `ckb-sync-changes`, `extract-transcript`,
+`ckb-project-summary`. Don't ask about these - just include them.
 
 `ghost-writer` and `clouddrift-docx` are not part of the default set (a
 general writing tool and a brand-specific export skill respectively, not
@@ -132,7 +132,7 @@ same shape.
 ### Step 7 - Write `.gitignore`
 
 Base rules (always): `libs/`, `linked/`, `tmp/`, `.DS_Store`. Since
-`export-starlight` and `export-okf` are in the default skill set (Step 3),
+`ckb-export-starlight` and `ckb-export-okf` are in the default skill set (Step 3),
 also always add `outputs/starlight` and `outputs/okf` - both exist to be
 gitignored precisely because those two skills are present by default.
 

.agents/skills/ckb-onboard-me/SKILL.md

@@ -0,0 +1,143 @@
+---
+name: ckb-onboard-me
+description: Given a topic, walk the wiki knowledge graph and print a guided reading order — a mini tour. Produces a short overview of the topic plus the best sequence of wiki pages to read and what you'll find in each, ordered so prerequisites come before the pages that build on them. Use when the user says "onboard me on X", "give me a reading order for X", "where do I start with X", "walk me through X", "mini tour of X", "guided tour of X", or "what should I read to understand X".
+---
+
+# Onboard me (guided wiki tour) skill
+
+## Purpose
+
+Turn a topic into a **reading order**: a short scene-setting overview followed
+by an ordered list of wiki pages to read, each with a one-line note on what
+you'll find there and why it comes at that point. It's a mini onboarding tour
+built by walking the knowledge graph outward from the topic, so a newcomer
+learns things in a sensible order — foundations first, then the topic itself,
+then what builds on it.
+
+This skill is **read-only**. It never writes to `wiki/`, so it does not touch
+`wiki/log.md`. It synthesizes a route through existing knowledge; it does not
+add new claims. If the wiki has nothing on the topic, say so — don't invent a
+tour.
+
+## Trigger phrases
+
+Use this skill when the user says things like:
+- "onboard me on X" / "get me up to speed on X"
+- "where do I start with X" / "what should I read to understand X"
+- "give me a reading order for X" / "reading list for X"
+- "walk me through X" / "mini tour of X" / "guided tour of X"
+
+## How to run this skill
+
+### Step 1 — Resolve the topic to a starting page
+
+Read the cheap indexes first, in cascade order (first match wins):
+
+1. `wiki/index.md` — match the topic against the **Use when** column.
+2. `wiki/entities/index.md` — match against entity titles and their `tldr`.
+3. If nothing local matches, check each `linked/<name>/` index, then each
+   `libs/<name>/` index (alphabetical). The local `wiki/` always wins if both
+   have a candidate.
+
+Pick the single best-matching page as the **anchor** of the tour.
+
+- **No match anywhere** — tell the user the wiki has nothing on that topic
+  yet. Offer the closest 2–3 pages by title/`tldr` if any are vaguely related,
+  and suggest running Ingest to add the material. Do not fabricate a tour.
+- **Several equally good anchors** — list them (title + `tldr`) and ask which
+  one to start from, or offer to build a short tour that covers all of them.
+
+### Step 2 — Walk the graph outward from the anchor
+
+Read `wiki/graph/edges.json`. Edges are typed relationships between entity
+pages (`uses`, `depends_on`, `caused`, `contradicts`, `supersedes`) with a
+`source` and a `target`. Starting from the anchor, do a breadth-first walk:
+
+- Collect every page directly connected to the anchor (anchor is `source` or
+  `target` of the edge).
+- Follow one more hop out from those pages. **Stop at 2 hops** — a tour is a
+  route, not the whole map. Keep a visited set so cycles don't loop.
+- Cap the tour at roughly **8 pages**. If the 2-hop neighbourhood is larger,
+  keep the pages closest to the anchor and highest `confidence` /
+  `retention: high`, and tell the user you trimmed it (say how many were left
+  out) rather than silently dropping them.
+
+**If `edges.json` is missing or empty** (no ingest has extracted edges yet),
+fall back to link-following: read the anchor page and collect the pages it
+links to via `[[wikilinks]]` and `[markdown](path.md)` links, then one hop out
+from those. Same 2-hop, ~8-page, visited-set rules apply. Note in the output
+that ordering came from page links rather than the typed graph.
+
+### Step 3 — Order the pages pedagogically
+
+The reading order is the whole point — don't just dump the neighbourhood.
+Order by dependency direction, not by hop distance alone:
+
+1. **Foundations first.** A page the anchor `depends_on` or `uses` is a
+   prerequisite — it comes *before* the anchor. Recurse: a prerequisite's own
+   prerequisites come before it.
+2. **The anchor** — the topic itself, once its groundwork is laid.
+3. **Builds-on / related** — pages that `depend_on` or `use` the anchor, or
+   are related without a clear dependency, come after. These are "where to go
+   next."
+4. Put `contradicts` / `superseded_by` links near the page they qualify, with
+   a note that they offer a competing or newer view.
+
+Within a tier, order by `confidence` then `last_updated` (higher/newer first)
+so the most solid reading comes first. Read each page's `tldr` (frontmatter)
+to write its one-line "what you'll find" — only open the body if the `tldr` is
+missing or too thin to describe the page.
+
+### Step 4 — Print the tour
+
+Print to chat (this skill produces a message, not a file). Use this shape:
+
+```markdown
+## Guided tour: [Topic]
+
+[2–3 sentence overview: what the topic is and what this tour will teach you,
+synthesized from the anchor page's tldr and its immediate context.]
+
+**Reading order:**
+
+1. **[Page title](wiki/entities/foo.md)** — *foundation.* [what you'll find,
+   and why it's first — e.g. "the concept everything here builds on."]
+2. **[Page title](wiki/entities/bar.md)** — *the core.* [what you'll find.]
+3. **[Page title](wiki/entities/baz.md)** — *builds on it.* [what you'll find.]
+   ...
+
+**After this you'll understand:** [one line on the payoff — what the reader
+can do or reason about once they've read the sequence.]
+```
+
+Rules for the output:
+- Use clickable markdown links to the actual pages (project-root-relative,
+  e.g. `wiki/entities/foo.md`), so the reader can jump straight in.
+- Label each step with its role in the tour (*foundation* / *core* /
+  *builds on it* / *alternative view*) so the ordering logic is visible.
+- Keep each "what you'll find" to one line, drawn from the page's `tldr`.
+- If pages came from `linked/` or `libs/`, link them with their full cascade
+  path and mark them as upstream.
+
+### Step 5 — Offer follow-ups
+
+Close with a short offer: to go deeper on any single step, to widen the tour
+(3+ hops), or to start a different topic. Don't act on these unless asked.
+
+## Edge cases
+
+- **Anchor has no edges and no outgoing links** — the tour is just the anchor.
+  Print its overview and say it's currently a standalone page with no mapped
+  connections; suggest an Ingest may add links later.
+- **Topic spans several disconnected clusters** — if the graph walk finds two
+  unrelated groups, present them as two short mini-tours under one topic rather
+  than forcing a single misleading sequence.
+- **Broken edge (points to a missing page)** — skip it silently in the tour,
+  but mention at the end that the graph has a dangling edge so the user can run
+  Lint. Do not fabricate the missing page.
+- **Very fresh material in `workload/` not yet in the wiki** — this skill tours
+  `wiki/` only. If the user expects a topic that was just discussed but not yet
+  ingested, note that it isn't in the wiki yet and point them at Ingest.
+- **Upstream-only topic** — if the anchor lives in `linked/`/`libs/` with no
+  local overlay, build the tour from the upstream KB's own index/links and mark
+  every step as upstream/read-only.

.agents/skills/ckb-project-summary/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: project-summary
+name: ckb-project-summary
 description: Generate or refresh a one-to-two-page project overview at the repo root, synthesized entirely from the current wiki/ contents — overview paragraph, project state, actions and their status, risks, and assumptions. Use when the user asks for "a project summary", "project overview", "give me the state of the project", "where do things stand", "summarize the project", or wants a quick top-level snapshot without reading the whole wiki.
 ---
 

.agents/skills/ckb-sync-changes/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: sync-changes
+name: ckb-sync-changes
 description: Reconcile this repo's git history with its origin remote — pull down remote commits, commit any local working-tree changes, resolve any conflicts with the user, then push. Use when the user asks to "sync changes", "sync with git", "sync with the remote", "sync with origin", "push and pull my changes", "reconcile git", or "sync the repo". This is a git-level operation, distinct from the content-level "Sync the wiki" / "Ingest" workflow in CLAUDE.md, which processes raw/inbox/ into structured wiki/ pages.
 ---
 
@@ -17,7 +17,7 @@ content, and never tries to semantically reconcile markdown or frontmatter —
 a conflicted file is just text with conflict markers until the user says
 otherwise.
 
-Unlike the `export-okf` skill, this skill **does** commit and push on its
+Unlike the `ckb-export-okf` skill, this skill **does** commit and push on its
 own once conflicts (if any) are resolved — that automation was explicitly
 requested for this skill.
 

workload/2026-07-15_summary.md

@@ -0,0 +1,7 @@
+# 2026-07-15 Summary
+
+## Git sync turn
+- User asked to commit all changes and push to the remote.
+- Read `wiki/index.md` for session startup context and used the `ckb-sync-changes` skill for repo-level git sync.
+- Confirmed the working tree contains skill directory renames from legacy names to `ckb-*` names plus this session summary.
+- Fetched `origin`; no remote branch heads were advertised, so the push will publish local `main` to `origin`.