From 753c415f5d7f7318d4d423320d3b59c20f4dd564 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Kope=C4=87?= Date: Wed, 15 Jul 2026 16:38:57 +0200 Subject: [PATCH] Sync: local changes as of 2026-07-15T17:00:00+02:00 --- README.md | 54 ++++++++++++++++++++++++++++------ workload/2026-07-15_summary.md | 7 +++++ 2 files changed, 52 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index 587bad1..e27a1ec 100644 --- a/README.md +++ b/README.md @@ -180,9 +180,40 @@ v0.1-conformant bundle at `outputs/okf/`, consumable by any generic OKF tool (e.g. Google's reference graph visualizer) without disturbing the richer internal schema (`confidence`/`quality`/`retention`/`supersedes`/dual-linking) that OKF doesn't natively understand. Implemented as a Claude Code Skill — -see `.claude/skills/ckb-export-okf/SKILL.md` — rather than baked into +see `.agents/skills/ckb-export-okf/SKILL.md` — rather than baked into `CLAUDE.md`/`AGENTS.md`, so the mapping ruleset only loads into context when -actually invoked. +actually invoked. `outputs/okf/` is gitignored — it's a fully-regenerated +build artifact, so each machine/tool regenerates it on demand rather than +carrying it in git history. + +### Starlight Export (on demand) +The wiki can also be exported into an Astro + Starlight-consumable form at +`outputs/starlight/`, producing a human-readable documentation website — +unlike the OKF export, which targets machine/tool consumption. A +deterministic Python script (`scripts/export_starlight.py`) handles +frontmatter remapping, dual-link collapsing, wikilink resolution, asset +copying, and sidebar generation; the agent's job is just to ask the two +setup questions (export scope: full runnable scaffold vs. content-only; +whether to include the log/error-book meta pages) and relay the script's +report. Also on-demand and skill-only — see +`.agents/skills/ckb-export-starlight/SKILL.md`. Like `outputs/okf/`, +`outputs/starlight/` is gitignored as a regenerated build artifact. + +### Guided Onboarding Tours (on demand) +Ask "onboard me on X" (or "where do I start with X", "mini tour of X") to get +a short, read-only guided reading order: an overview paragraph plus an +ordered list of wiki pages to read, built by walking the knowledge graph +outward from the best-matching page (foundations first, then the topic +itself, then what builds on it). Never writes to `wiki/`. See +`.agents/skills/ckb-onboard-me/SKILL.md`. + +### Project Summary (on demand) +Ask for "a project summary" (or "where do things stand", "catch me up on the +project") to regenerate `PROJECT-OVERVIEW.md` at the repo root — a +one-to-two-page snapshot (overview, project state, actions & status, risks, +assumptions) synthesized entirely from the current `wiki/` contents and its +knowledge graph. Always overwritten in full on re-run, never hand-appended +to. See `.agents/skills/ckb-project-summary/SKILL.md`. ### Git Sync (on demand) This repo's own git history can be reconciled with its `origin` remote on @@ -222,7 +253,12 @@ content-level "Sync the wiki" / "Ingest" workflow, which processes | File | Purpose | |------|---------| | `AGENTS.md` | Full instruction for any AI coding agent | -| `CLAUDE.md` | Same instructions, auto-detected by Claude Code | +| `CLAUDE.md` | Symlink to `AGENTS.md`, auto-detected by Claude Code | + +Skills live in one shared location, `.agents/skills/`, so any agent tooling +that reads that convention picks them up. `.claude/skills` is a symlink to +`.agents/skills` — Claude Code sees the same skill set without a second +copy to keep in sync. --- @@ -234,9 +270,9 @@ content-level "Sync the wiki" / "Ingest" workflow, which processes - The `wiki/index.md` routing table is the most important file — keep it current. - Confidence, quality, and freshness let you trust the right content and flag the rest for review. -- The `tmp/` and `libs/` directories are gitignored. `outputs/` is tracked - — commit generated artifacts you want to preserve. `outputs/okf/` is a - fully-regenerated build artifact (never hand-patched); it stays tracked too - since an OKF bundle is only useful to teammates if it's actually committed, - but the export skill never commits on its own — review the diff and commit - it yourself when you want to publish an update. +- The `tmp/` and `libs/` directories are gitignored. `outputs/` itself is + tracked, but its regenerated build subdirectories, `outputs/okf/` and + `outputs/starlight/`, are gitignored — each is fully reproducible from + `wiki/` on demand, so there's nothing to reconcile by carrying it in git + history. Commit other, hand-maintained artifacts under `outputs/` as + normal. diff --git a/workload/2026-07-15_summary.md b/workload/2026-07-15_summary.md index a5ed5cc..44b9146 100644 --- a/workload/2026-07-15_summary.md +++ b/workload/2026-07-15_summary.md @@ -27,3 +27,10 @@ ## Placeholder commit sync turn - User asked to commit and push all changes to the remote repos. - Confirmed the visible changes are `.gitadd` placeholders for empty directories, `.gitignore` exceptions for `libs/.gitadd` and `tmp/.gitadd`, deletion of `.claude/settings.json`, and the workload note. + +## README audit and update turn +- User asked to analyse the root `README.md` for staleness and, after review, to apply fixes. +- Found the README claimed `outputs/okf/` "stays tracked" in git, but `.gitignore` has excluded both `outputs/okf` and `outputs/starlight` since their introduction (commit `eebfb07`) — the claim never matched actual repo behavior. +- Found three existing skills undocumented in README's Features list: `ckb-export-starlight`, `ckb-onboard-me`, `ckb-project-summary`. +- Found the `.agents/skills/` shared skill directory (with `.claude/skills` symlinked to it) — the actual mechanism behind the README's advertised "multi-agent support" — was not documented anywhere. +- Updated README.md: corrected the `outputs/okf`/`outputs/starlight` gitignore claim, added Features sections for the three missing skills, added a note on the `.agents/skills` / `.claude/skills` symlink architecture, and fixed the `CLAUDE.md` table row to say it's a symlink to `AGENTS.md` rather than "same instructions."