Add connector-backed libs/ with self-contained external source indexing
libs/<name>/ now supports a second population mode alongside git-copy clones: a user-authored source.yaml declares a live external source (SharePoint, Google Drive, a plain URL, or another connector), and the new ckb-index-external skill builds a self-contained generated index for it (index.md/entities/graph/log.md), scoped entirely to that connector and never blended into the main wiki/. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
This commit is contained in:
Michał Kopeć
parent
59173c86a4
commit
55c8c352d1
11 changed files with 469 additions and 45 deletions
|
|
@ -135,7 +135,7 @@ the report rather than silently patching the export.
|
|||
|
||||
Before reporting done, re-check the *generated* `outputs/okf/` bundle
|
||||
against OKF's own conformance criteria (the same shape of check `CLAUDE.md`
|
||||
§5 step 1 runs against the source wiki):
|
||||
§6 step 1 runs against the source wiki):
|
||||
|
||||
- Every non-reserved `.md` file has frontmatter with a non-empty `type`.
|
||||
- The root `index.md`'s frontmatter contains only `okf_version` (or is
|
||||
|
|
@ -168,7 +168,7 @@ Tell the user:
|
|||
spec-valid, don't skip the directory entirely.
|
||||
- **A wiki page missing `type`:** per Step 3, use `type: unknown` and flag
|
||||
it in the report — this indicates the source wiki itself failed lint's
|
||||
conformance check (see `CLAUDE.md` §5 step 1), which is worth surfacing
|
||||
conformance check (see `CLAUDE.md` §6 step 1), which is worth surfacing
|
||||
to the user rather than quietly masking it in the export.
|
||||
- **A future `wiki/archived/` directory:** export it like any other
|
||||
subdirectory (mirror the structure, apply the same per-file rules) —
|
||||
|
|
|
|||
175
.agents/skills/ckb-index-external/SKILL.md
Normal file
175
.agents/skills/ckb-index-external/SKILL.md
Normal file
|
|
@ -0,0 +1,175 @@
|
|||
---
|
||||
name: ckb-index-external
|
||||
description: Walk every connector-backed libs/<name>/ (identified by a source.yaml declaring a live external source — SharePoint, Google Drive, a plain URL, or another connector) and build/refresh a self-contained generated index for it — index.md/entities/graph/log.md, mirroring wiki/'s own shape but scoped entirely to that one connector. Never touches wiki/, never touches source.yaml, never touches a git-copy lib. Use when the user says "index external sources", "index libs", "refresh the external index", or "scan the SharePoint/Drive folder". This is the on-demand workflow from CLAUDE.md/AGENTS.md §4, distinct from `ckb-ingest` (which processes raw/inbox/ into wiki/) and from a plain git-copy libs/<name>/ (a frozen clone, never touched by any skill).
|
||||
---
|
||||
|
||||
# Index external sources skill
|
||||
|
||||
## Purpose
|
||||
|
||||
Give `libs/<name>/` a second population mode alongside the existing
|
||||
git-copy one: a `libs/<name>/source.yaml` declares a *live* external
|
||||
source — a SharePoint folder, a Google Drive folder, a plain URL, or
|
||||
another connector — that the user doesn't want to fully mirror locally.
|
||||
This skill walks that source and builds a small, self-contained index of
|
||||
what's there: one entity page per document found, plus the same
|
||||
`index.md`/`graph`/`log.md` shape `wiki/` already uses, rooted at
|
||||
`libs/<name>/` instead.
|
||||
|
||||
This is deliberately **not** blended into the main `wiki/entities/` or
|
||||
`wiki/graph/edges.json` — the generated index lives entirely inside its own
|
||||
`libs/<name>/`, at the lowest cascade layer, the same way a git-cloned
|
||||
KB's own files would. If something in it needs to override or correct what
|
||||
the connector says, that's what writing the corrected version into `wiki/`
|
||||
is for (cascade priority already covers that — `wiki/` always wins).
|
||||
|
||||
This skill only ever writes within a connector-backed `libs/<name>/` (never
|
||||
`source.yaml` itself, never a git-copy lib, never anything under `wiki/`)
|
||||
— and it never touches this repo's own git remote; pushing the resulting
|
||||
changes is a separate, explicit step (see Step 6).
|
||||
|
||||
## Trigger phrases
|
||||
|
||||
Use this skill when the user says:
|
||||
- "Index external sources"
|
||||
- "Index libs"
|
||||
- "Refresh the external index"
|
||||
- "Scan the SharePoint/Drive folder" (or similarly names a specific
|
||||
connector)
|
||||
|
||||
Do **not** use this skill for "Ingest" / "Sync the wiki" (that's
|
||||
`ckb-ingest` — raw material into `wiki/`, unrelated to `libs/`) or for
|
||||
"Lint" (that's `ckb-lint`, which now also health-checks a connector's own
|
||||
generated index, but doesn't build it in the first place).
|
||||
|
||||
## How to run this skill
|
||||
|
||||
### Step 1 — Find connector-backed libs
|
||||
|
||||
Scan `libs/*/` for a `source.yaml`. A `libs/<name>/` with one is
|
||||
connector-backed and in scope; a `libs/<name>/` without one is a git-copy
|
||||
lib and stays completely untouched by this skill.
|
||||
|
||||
If no `libs/<name>/source.yaml` exists anywhere, tell the user there's
|
||||
nothing to index yet and how to add one (a `source.yaml` with `connector`
|
||||
and `location`), and stop — don't fabricate an index from nothing.
|
||||
|
||||
### Step 2 — Read the config and resolve the connector
|
||||
|
||||
Read `source.yaml`:
|
||||
```yaml
|
||||
connector: sharepoint # sharepoint | google_drive | web | custom — open string, not a fixed enum
|
||||
location: "https://contoso.sharepoint.com/sites/Finance/Shared Documents/Reports"
|
||||
description: "Finance team's shared reports folder" # optional
|
||||
```
|
||||
Resolve `connector` to whatever live tool is actually available this
|
||||
session:
|
||||
- `sharepoint` / a Microsoft-hosted location → search (`ToolSearch`) for a
|
||||
connected Microsoft 365 MCP tool.
|
||||
- `google_drive` → search for a connected Google Drive MCP tool.
|
||||
- `web` / `custom` / anything else with a plain URL → `WebFetch`.
|
||||
|
||||
If the needed connector isn't authorized in this session (per the current
|
||||
MCP auth state), **don't fail the whole run** — tell the user which
|
||||
connector needs authorizing (via claude.ai connector settings, or `claude
|
||||
mcp`/`/mcp` for non-claude.ai servers), skip that source, and continue with
|
||||
any others.
|
||||
|
||||
### Step 3 — Enumerate and summarize documents
|
||||
|
||||
For each document found at the location:
|
||||
- Read enough content to write a real 1-2 sentence `tldr` when the
|
||||
connector allows fetching content.
|
||||
- If only metadata is available (listing only, no read access), say so
|
||||
honestly in the `tldr` (e.g. "Metadata only — read access not granted")
|
||||
and set `confidence` low (e.g. 0.3) rather than fabricating a summary.
|
||||
|
||||
Create/update one entity page per document at
|
||||
`libs/<name>/entities/<doc-slug>.md`:
|
||||
```yaml
|
||||
---
|
||||
type: document
|
||||
resource: <document's own URL/path>
|
||||
tldr: ...
|
||||
confidence: 0.3–0.9 # per the rule above
|
||||
quality: ...
|
||||
last_updated: YYYY-MM-DD
|
||||
freshness_window_days: 30 # shorter than a typical wiki page — external sources change without notice
|
||||
retention: medium
|
||||
---
|
||||
```
|
||||
|
||||
### Step 4 — Update the hub page and graph
|
||||
|
||||
Create/update `libs/<name>/index.md` — the root routing page for this
|
||||
connector, mirroring `wiki/index.md`'s own role:
|
||||
```yaml
|
||||
---
|
||||
type: external-source
|
||||
resource: <location, from source.yaml>
|
||||
tldr: One sentence — what this source is and how many documents were found
|
||||
last_updated: YYYY-MM-DD
|
||||
---
|
||||
```
|
||||
followed by a short routing table pointing to `entities/index.md` and
|
||||
`graph/index.md`.
|
||||
|
||||
Record any real relationships between documents (e.g. folder hierarchy) as
|
||||
edges in `libs/<name>/graph/edges.json`, using a `contains`/`part_of`-style
|
||||
edge type — this is fine to be thin or empty for a flat source with no
|
||||
useful structure beyond a document list.
|
||||
|
||||
### Step 5 — Update index/log, following the Recursive Index & Log Convention
|
||||
|
||||
Update `libs/<name>/entities/index.md` and `libs/<name>/graph/index.md`
|
||||
(flat bullet lists, no frontmatter, same convention as `wiki/entities/
|
||||
index.md`/`wiki/graph/index.md`). Log every created/updated page in
|
||||
`libs/<name>/log.md`, same reverse-chronological format as Rule B
|
||||
(`CLAUDE.md`/`AGENTS.md` §7) — this log is independent of `wiki/log.md`;
|
||||
**nothing under `wiki/` is touched by this skill at all.**
|
||||
|
||||
### Step 6 — Remind to review and sync
|
||||
|
||||
This is always the last step, every time this skill makes any change at
|
||||
all. Close with a short reminder — do not sync or push anything yourself
|
||||
here:
|
||||
|
||||
> "External source indexing complete for `libs/<name>/` — see
|
||||
> `libs/<name>/log.md` for the details. Please review the changes, and
|
||||
> once you're happy with them, say 'sync changes' to commit and push them
|
||||
> to `origin`."
|
||||
|
||||
If nothing was actually indexed (no connector-backed libs found, or every
|
||||
source was skipped for lack of authorization), skip this reminder.
|
||||
|
||||
## Edge cases
|
||||
|
||||
- **No connector-backed `libs/<name>/` exists** — report that and explain
|
||||
how to add one; don't touch anything.
|
||||
- **Connector not authorized this session** — report which one and how to
|
||||
authorize it (claude.ai connector settings / `claude mcp` / `/mcp`),
|
||||
skip that source, keep going with the rest. Never ask the user for
|
||||
tokens or callback URLs.
|
||||
- **Re-running against an already-indexed source** — refresh existing
|
||||
entity pages in place (update `tldr`/`last_updated`/`confidence`); never
|
||||
duplicate a document's page.
|
||||
- **A previously-indexed document is no longer found at the source** —
|
||||
don't delete its page. Update its `tldr` with a note ("No longer found
|
||||
at source as of YYYY-MM-DD") and set `retention: low`, so the existing
|
||||
`ckb-lint` retention sweep archives it naturally on a later pass — no new
|
||||
archival mechanism needed.
|
||||
- **A source is very large** — cap what gets fully fetched/summarized in
|
||||
one run and explicitly report what was skipped (e.g. "42 of ~300
|
||||
documents summarized this pass — re-run to continue"). Never silently
|
||||
truncate while implying full coverage.
|
||||
- **`libs/<name>/` has both real content files and a `source.yaml`** —
|
||||
ambiguous and out of scope for this skill to resolve; report it and stop
|
||||
for that folder (this is the same case `ckb-lint`'s new external-source
|
||||
config check flags).
|
||||
- **`source.yaml` is missing `connector` or `location`** — report it as
|
||||
malformed and skip that source; don't guess at intent.
|
||||
|
||||
---
|
||||
|
||||
*Licensed under the Apache License, Version 2.0 — see [LICENSE](../../../LICENSE)
|
||||
at the repository root, or <http://www.apache.org/licenses/LICENSE-2.0>.*
|
||||
|
|
@ -92,7 +92,7 @@ description. If the page lives in a subdirectory, also add it to that
|
|||
subdirectory's own `index.md`. Append a log entry to the most specific
|
||||
applicable log — the subdirectory's `log.md` if it has one, otherwise the
|
||||
root `wiki/log.md` — following the format in Rule B (`CLAUDE.md`/
|
||||
`AGENTS.md` §6).
|
||||
`AGENTS.md` §7).
|
||||
|
||||
If this step creates a brand-new `wiki/<topic>/` subdirectory, immediately
|
||||
create that subdirectory's `index.md` per the Recursive Index & Log
|
||||
|
|
@ -122,7 +122,7 @@ process), skip this reminder — there's nothing to review or sync.
|
|||
considered, but note in the ingest report that it produced no wiki
|
||||
change.
|
||||
- **Conflicting information vs. an existing local wiki page** — this is a
|
||||
supersession case (Rule via `CLAUDE.md`/`AGENTS.md` §5 lint), not a
|
||||
supersession case (Rule via `CLAUDE.md`/`AGENTS.md` §6 lint), not a
|
||||
silent overwrite: update the existing page if the new source is clearly
|
||||
more current/corroborated, and link `supersedes`/`superseded_by` if an
|
||||
older version is worth preserving rather than edited in place.
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
---
|
||||
name: ckb-lint
|
||||
description: Health-check the wiki/ — conformance, freshness, confidence decay, retention sweep, supersession detection, orphan detection, graph consistency, index/log consistency, and error-book entries — auto-fixing what it safely can and reporting the rest, then reminding the user to review and sync to origin. Use when the user says "Lint", "health-check the wiki", "check the wiki", or asks for a periodic/scheduled wiki health check. This is the maintenance workflow from CLAUDE.md/AGENTS.md §5, distinct from `ckb-ingest` (which adds new content) and `ckb-sync-changes` (a pure git-level operation with no wiki synthesis at all).
|
||||
description: Health-check the wiki/ — conformance, freshness, confidence decay, retention sweep, supersession detection, orphan detection, graph consistency, index/log consistency, and error-book entries — auto-fixing what it safely can and reporting the rest, then reminding the user to review and sync to origin. Also runs the same checks against each connector-backed libs/<name>/'s own generated index (see ckb-index-external), plus a source.yaml validity check, without ever touching a git-copy lib or a connector's source.yaml itself. Use when the user says "Lint", "health-check the wiki", "check the wiki", or asks for a periodic/scheduled wiki health check. This is the maintenance workflow from CLAUDE.md/AGENTS.md §6, distinct from `ckb-ingest` (which adds new content) and `ckb-sync-changes` (a pure git-level operation with no wiki synthesis at all).
|
||||
---
|
||||
|
||||
# Lint skill
|
||||
|
|
@ -18,10 +18,13 @@ Implemented as a skill (rather than living inline in
|
|||
actually invoked — on demand, or on a schedule if the user has set one up.
|
||||
|
||||
This skill only ever writes within `wiki/` (including moves into
|
||||
`wiki/archived/`). It never touches `linked/` or `libs/` — those are
|
||||
immutable upstream sources of truth — and it never touches this repo's own
|
||||
git remote; pushing the resulting changes is a separate, explicit step
|
||||
(see the final step below).
|
||||
`wiki/archived/`) and, for any connector-backed `libs/<name>/` (one with a
|
||||
`source.yaml` — see `CLAUDE.md`/`AGENTS.md` §1/§4), within that connector's
|
||||
own agent-owned generated index (`index.md`/`entities/`/`graph/`/`log.md`).
|
||||
It never touches `linked/`, a git-copy `libs/<name>/`, or a connector's
|
||||
`source.yaml` itself — those stay immutable upstream sources of truth — and
|
||||
it never touches this repo's own git remote; pushing the resulting changes
|
||||
is a separate, explicit step (see the final step below).
|
||||
|
||||
## Trigger phrases
|
||||
|
||||
|
|
@ -40,6 +43,14 @@ repo's own commit history with `origin`, no wiki content involved).
|
|||
Work through each check in order. A malformed page breaks every later
|
||||
check's ability to reason about it, so conformance comes first.
|
||||
|
||||
Checks 1-9 below are written against `wiki/`, but the same checks also run
|
||||
a second time against each connector-backed `libs/<name>/`'s own generated
|
||||
index — scoped entirely to that one connector's `index.md`/`entities/`/
|
||||
`graph/`/`log.md`. Findings and fixes there are logged in that connector's
|
||||
own `log.md`, never in `wiki/log.md`. A git-copy `libs/<name>/` (no
|
||||
`source.yaml`) and any `source.yaml` itself are never touched by any of
|
||||
these checks.
|
||||
|
||||
### 1 — Conformance check
|
||||
|
||||
Verify every non-reserved `.md` file under `wiki/` (i.e. excluding
|
||||
|
|
@ -63,7 +74,7 @@ check. Pages that fall below 0.3 confidence get flagged for re-review.
|
|||
|
||||
Move `retention: low` pages older than 2× their `freshness_window_days`
|
||||
into `wiki/archived/`. Never delete — always move, and log the move (see
|
||||
Rule B in `CLAUDE.md`/`AGENTS.md` §6) with a note explaining why.
|
||||
Rule B in `CLAUDE.md`/`AGENTS.md` §7) with a note explaining why.
|
||||
|
||||
### 5 — Supersession detection
|
||||
|
||||
|
|
@ -102,6 +113,14 @@ recurring format mismatch, the same kind of orphan appearing again) in
|
|||
constraint that should prevent recurrence. A one-off, isolated issue
|
||||
doesn't need an Error Book entry — this is for patterns, not incidents.
|
||||
|
||||
### 10 — External source config check
|
||||
|
||||
For each `libs/<name>/source.yaml`, verify it has a non-empty `connector`
|
||||
and `location` — report only, this one file is never edited by any skill.
|
||||
Also flag (report only) a `libs/<name>/` that ambiguously has both real
|
||||
content files and a `source.yaml` — that's a configuration conflict for the
|
||||
user to resolve, not something to guess at.
|
||||
|
||||
### Auto-fix vs. report
|
||||
|
||||
Auto-fix what can be done safely and mechanically: broken links, missing
|
||||
|
|
@ -121,6 +140,10 @@ anything yourself here:
|
|||
> you're happy with them, say 'sync changes' to commit and push them to
|
||||
> `origin`."
|
||||
|
||||
If any connector-backed `libs/<name>/` was also touched, mention it
|
||||
separately (its own `log.md`, not `wiki/log.md`) rather than folding it
|
||||
into the same sentence.
|
||||
|
||||
If the lint pass made no changes at all (clean bill of health, nothing to
|
||||
fix or flag), skip this reminder — there's nothing to review or sync.
|
||||
|
||||
|
|
|
|||
7
.gitignore
vendored
7
.gitignore
vendored
|
|
@ -1,5 +1,12 @@
|
|||
libs/*
|
||||
!libs/.gitadd
|
||||
!libs/*/
|
||||
libs/*/*
|
||||
!libs/*/source.yaml
|
||||
!libs/*/index.md
|
||||
!libs/*/log.md
|
||||
!libs/*/entities/
|
||||
!libs/*/graph/
|
||||
tmp/*
|
||||
!tmp/.gitadd
|
||||
outputs/starlight
|
||||
|
|
|
|||
33
AGENTS.md
33
AGENTS.md
|
|
@ -15,8 +15,13 @@ You possess full autonomy over local directory structure, file naming convention
|
|||
The root directory contains exactly seven top-level entries. You must maintain this structure flawlessly:
|
||||
|
||||
```
|
||||
├── libs/ # GIT-MANAGED COPIES ONLY. Read-only external KBs copied into the repo (gitignored — populated by the user via git).
|
||||
│ └── <name>/ # Individual external knowledge base (immutable — never write here).
|
||||
├── libs/ # Read-only external sources, one of two kinds per <name>/ subfolder:
|
||||
│ └── <name>/ # - GIT-COPY: a git-managed clone/ZIP unpack, gitignored, fully immutable — never write here.
|
||||
│ # - CONNECTOR: identified by a user-authored source.yaml (connector + location).
|
||||
│ # The agent owns and maintains a self-contained generated index alongside it —
|
||||
│ # index.md/entities/graph/log.md, mirroring wiki/'s own shape but scoped entirely
|
||||
│ # to this one connector. See §4 EXTERNAL SOURCE INDEXING. source.yaml itself stays
|
||||
│ # user-only, same as everything in a git-copy lib.
|
||||
├── linked/ # SYMLINKS ONLY. Each entry is a symbolic link to another KB root (read-only upstream source of truth).
|
||||
│ └── <name>/ # Individual upstream knowledge base (immutable — never write here).
|
||||
├── outputs/ # MANAGED BY AGENT. Generated artifacts, exports, compiled files produced from the wiki.
|
||||
|
|
@ -43,10 +48,10 @@ When searching for any entity, concept, or file, use the following cascade (firs
|
|||
|
||||
1. **Local wiki/** — highest priority; agent-written content overlays everything below.
|
||||
2. **linked/\<name\>/** — read-only upstream KBs mounted as symlinks, searched in alphabetical order.
|
||||
3. **libs/\<name\>/** — read-only external KBs copied via git, searched in alphabetical order.
|
||||
3. **libs/\<name\>/** — read-only external sources, searched in alphabetical order. For a git-copy lib this is its cloned files; for a connector-backed lib (one with a `source.yaml`) this layer's content *is* the agent-generated index (`index.md`/`entities/`/`graph/`) built by the `ckb-index-external` skill, not raw copied files — see §4.
|
||||
4. If no match is found anywhere, treat the entity as unknown.
|
||||
|
||||
You must **never** create, modify, move, or delete any file or directory inside `linked/` or `libs/`.
|
||||
You must **never** create, modify, move, or delete any file or directory inside `linked/` or a git-copy `libs/<name>/`. The one exception is a connector-backed `libs/<name>/`'s own generated index, which the agent owns and maintains exactly like `wiki/` — see Rule A in §7.
|
||||
|
||||
### Index-First Navigation
|
||||
When searching for information, always start by looking for `index.md` files.
|
||||
|
|
@ -65,6 +70,7 @@ Index-First Navigation only works if subdirectory indexes actually exist. Mainta
|
|||
- Every `wiki/` subdirectory that groups multiple pages (`entities/`, `graph/`, and any future topic folder) must contain its own `index.md`. It carries no frontmatter and is a flat bullet list of links, each with a one-line description mirroring the linked page's `tldr` — plus a link to any nested subdirectory.
|
||||
- A subdirectory may also keep its own `log.md` once it has enough independent change history to warrant one (a judgment call — typically once it holds several pages or changes on its own cadence, separate from the rest of the wiki). Entries follow the same reverse-chronological format as Rule B.
|
||||
- The root `wiki/log.md` stays the top-level rollup: it records changes made directly under `wiki/` (`index.md`, `overview.md`, `error-book.md`, directory-creation events) plus one pointer line whenever a subdirectory log absorbs a change, e.g. `- See wiki/entities/log.md for entity-page changes on this date.` Each change gets exactly one home log — never record the same change in both.
|
||||
- The same convention applies verbatim inside a connector-backed `libs/<name>/` (§4) — its generated `index.md`/`entities/index.md`/`graph/index.md`/`log.md` mirror this pattern exactly, scoped entirely to that one connector. Its `log.md` is independent of `wiki/log.md` — never record a connector-indexing change in both.
|
||||
|
||||
### Lazy-Loading with "Use When" Triggers
|
||||
The `wiki/index.md` is a routing table. Each entry has a **Use when** column
|
||||
|
|
@ -119,7 +125,13 @@ When the user says "Ingest", "Sync the wiki", or "Update the Wiki" (for syncing
|
|||
|
||||
---
|
||||
|
||||
## 4. QUERY WORKFLOW
|
||||
## 4. EXTERNAL SOURCE INDEXING (TRIGGERED ON DEMAND)
|
||||
|
||||
When the user says "Index external sources" (or "index libs", "refresh the external index"), run the **ckb-index-external** Claude Code Skill — see `.agents/skills/ckb-index-external/SKILL.md` — rather than following inline steps here, so the full procedure only loads into context when actually invoked. It walks every connector-backed `libs/<name>/` (one with a `source.yaml` — see §1), resolves the declared connector to whatever live tool is available this session (SharePoint/Drive MCP connector, or `WebFetch` for a plain URL), and builds/refreshes that connector's own self-contained `index.md`/`entities/`/`graph/`/`log.md`. This never touches `wiki/`, never touches `source.yaml`, and never touches a git-copy lib.
|
||||
|
||||
---
|
||||
|
||||
## 5. QUERY WORKFLOW
|
||||
|
||||
When answering a question or researching a topic:
|
||||
|
||||
|
|
@ -127,20 +139,22 @@ When answering a question or researching a topic:
|
|||
2. **Read TLDRs** — for any matched page, read its `tldr:` frontmatter first. If it answers the query, stop.
|
||||
3. **Load full pages** — only if the TLDR was insufficient.
|
||||
4. **Walk the graph** — if the entity has relationships in `wiki/graph/edges.json`, follow them to discover connected pages (e.g. "what depends on X?").
|
||||
5. **Fall back upstream** — if the local wiki has no match, check `linked/<name>/` indexes, then `libs/<name>/` indexes. Apply cascade priority throughout.
|
||||
5. **Fall back upstream** — if the local wiki has no match, check `linked/<name>/` indexes, then `libs/<name>/` indexes (for a connector-backed lib, that means its generated `entities/`/`index.md`, not the live source directly — if it's not there yet, suggest running "index external sources" rather than fetching the live source ad hoc). Apply cascade priority throughout.
|
||||
|
||||
---
|
||||
|
||||
## 5. MAINTENANCE WORKFLOW (LINT)
|
||||
## 6. MAINTENANCE WORKFLOW (LINT)
|
||||
|
||||
Periodically (or when asked to "Lint"), run the **ckb-lint** Claude Code Skill — see `.agents/skills/ckb-lint/SKILL.md` — rather than following inline steps here, so the full checklist (conformance, freshness, confidence decay, retention sweep, supersession detection, orphan detection, graph consistency, index/log consistency, error-book entries, auto-fix vs. report, then a reminder to review and sync) only loads into context when actually invoked.
|
||||
|
||||
---
|
||||
|
||||
## 6. COMPLIANCE & LOGGING RULES (NON-NEGOTIABLE)
|
||||
## 7. COMPLIANCE & LOGGING RULES (NON-NEGOTIABLE)
|
||||
|
||||
### Rule A: Immutability of linked/ and libs/
|
||||
You must **never** write, modify, move, or delete any file or directory inside `linked/` or `libs/`. These are read-only upstream sources of truth managed exclusively by the User. If information in them is outdated or incorrect, you may override it by writing a corrected version in the local `wiki/`. The local version will take priority in the cascade lookup.
|
||||
You must **never** write, modify, move, or delete any file or directory inside `linked/` or a git-copy `libs/<name>/`. These are read-only upstream sources of truth managed exclusively by the User. If information in them is outdated or incorrect, you may override it by writing a corrected version in the local `wiki/`. The local version will take priority in the cascade lookup.
|
||||
|
||||
**Exception — connector-backed `libs/<name>/`:** identified by the presence of a `source.yaml` (see §1). Its `source.yaml` is user-authored and stays just as untouchable as anything else here. But everything else in that folder — `index.md`, `entities/`, `graph/`, `log.md` — is a generated index the agent owns and maintains exactly as it would `wiki/`, built and refreshed by the `ckb-index-external` skill (§4). This exception applies only to a `libs/<name>/` that has a `source.yaml`; a plain git-copy lib has no such carve-out.
|
||||
|
||||
### Rule B: The Wiki Change Log (`wiki/log.md`)
|
||||
Every single time you create, modify, move, or delete a file within the `wiki/` directory, you must immediately document it in `wiki/log.md` before proceeding.
|
||||
|
|
@ -171,6 +185,7 @@ After every conversational turn where you take any action (read, write, search,
|
|||
Follow these event-driven behaviors:
|
||||
|
||||
- **On new source in inbox** — on the next ingest, auto-process: extract entities, update graph, update index, write to log.
|
||||
- **On new or changed `libs/<name>/source.yaml`** — on the next "index external sources" run, process it: resolve the connector, enumerate documents, build/refresh that connector's own `index.md`/`entities/`/`graph/`/`log.md`.
|
||||
- **On session start** — read `wiki/index.md` and the latest `workload/` summary to load relevant context. Also check for unsynchronized changes (`git status` — uncommitted local changes, or the local branch ahead/behind its remote-tracking ref) and, if any are found, tell the user and suggest running the `ckb-sync-changes` skill before proceeding. This is a cheap, read-only check (no `git fetch`) — a heads-up, not a substitute for actually running that skill.
|
||||
- **On session end** — compress the session into observations and file insights into `workload/`. Also re-run the same unsynchronized-changes check as at session start — the session's own work may have just created new local changes — and suggest `ckb-sync-changes` if anything is now pending.
|
||||
- **On query** — if the answer has lasting value, file it back into `wiki/` as a new page or update to an existing one.
|
||||
|
|
|
|||
74
MANUAL.md
74
MANUAL.md
|
|
@ -55,7 +55,7 @@ If the target folder already looks like a KB (it has a `wiki/` or
|
|||
### Building on top of someone else's wiki
|
||||
|
||||
A Cascade KB can sit on top of one or more *upstream* knowledge bases,
|
||||
which stay entirely read-only. There are two ways to mount one:
|
||||
which stay entirely read-only. There are three ways to mount one:
|
||||
|
||||
- **Symlink** (another KB on your own machine, or one you maintain
|
||||
elsewhere and want live-linked):
|
||||
|
|
@ -73,13 +73,29 @@ which stay entirely read-only. There are two ways to mount one:
|
|||
frozen, read-only copy either way; the only difference is you won't be
|
||||
able to `git pull` it later to refresh — to update it, just re-download
|
||||
the ZIP and unpack it over the old contents.
|
||||
- **Connector** (a live external source you *don't* want a full local
|
||||
copy of — a SharePoint folder, a Google Drive folder, or another
|
||||
connected source): create `libs/<name>/source.yaml` yourself:
|
||||
```yaml
|
||||
connector: sharepoint
|
||||
location: "https://contoso.sharepoint.com/sites/Finance/Shared Documents/Reports"
|
||||
description: "Finance team's shared reports folder"
|
||||
```
|
||||
then say "index external sources." The agent reads the config, connects
|
||||
to whatever's available that session (a connected Microsoft 365/Google
|
||||
Drive tool, or a plain URL fetch), and builds a short index of what it
|
||||
finds — one entry per document — inside that same `libs/<name>/` folder.
|
||||
See [§6](#6-use-cases) for a worked example and what the result looks
|
||||
like.
|
||||
|
||||
Either way, once it's mounted, just ask questions normally — the agent
|
||||
checks your local `wiki/` first, then walks `linked/`, then `libs/`, and
|
||||
uses whichever has the answer. You never edit files inside `linked/` or
|
||||
`libs/` directly; if something there is wrong or outdated, you fix it by
|
||||
writing the corrected version into your own local `wiki/`, which always
|
||||
wins.
|
||||
uses whichever has the answer. You never edit files inside `linked/` or a
|
||||
git-copy `libs/<name>/` directly; if something there is wrong or outdated,
|
||||
you fix it by writing the corrected version into your own local `wiki/`,
|
||||
which always wins. (A connector-backed `libs/<name>/` is the one place the
|
||||
agent *does* write on your behalf — see [§6](#6-use-cases) — but even
|
||||
there, `source.yaml` itself stays yours to edit, never the agent's.)
|
||||
|
||||
---
|
||||
|
||||
|
|
@ -396,6 +412,49 @@ Covered in full in [§2](#2-adding-knowledge) — the short version: drop it
|
|||
in `raw/inbox/` and say "Ingest," or just tell the agent in chat if it's
|
||||
small enough to state directly.
|
||||
|
||||
### Index an external source
|
||||
|
||||
Say:
|
||||
|
||||
> "Index external sources." (or "index libs," "refresh the external
|
||||
> index")
|
||||
|
||||
This walks every `libs/<name>/` that has a `source.yaml` (see
|
||||
[§1](#building-on-top-of-someone-elses-wiki)) and builds a short index of
|
||||
what it finds — one entry per document, plus an overview page — entirely
|
||||
inside that same `libs/<name>/` folder. Nothing under `wiki/` is touched.
|
||||
|
||||
Example:
|
||||
|
||||
> *You create `libs/finance-reports/source.yaml`:*
|
||||
> ```yaml
|
||||
> connector: sharepoint
|
||||
> location: "https://contoso.sharepoint.com/sites/Finance/Shared Documents/Reports"
|
||||
> description: "Finance team's shared reports folder"
|
||||
> ```
|
||||
> *then say "Index external sources."*
|
||||
>
|
||||
> The agent connects using whatever's available that session (a connected
|
||||
> Microsoft 365 tool, in this case), lists the documents in that folder,
|
||||
> reads enough of each to write a short summary, and creates
|
||||
> `libs/finance-reports/index.md` (an overview of the source) plus one
|
||||
> page per document under `libs/finance-reports/entities/`, cross-linked
|
||||
> via `libs/finance-reports/graph/edges.json`. It logs everything in
|
||||
> `libs/finance-reports/log.md` — a log that's entirely separate from
|
||||
> `wiki/log.md`, since this index is scoped to that one connector rather
|
||||
> than blended into your main wiki. It finishes by reminding you to review
|
||||
> the result and say "sync changes" once you're happy with it.
|
||||
|
||||
If a connector needs authorizing (e.g. a SharePoint or Google Drive
|
||||
connection that isn't set up yet), the agent tells you which one and where
|
||||
to authorize it, then continues with any other configured sources rather
|
||||
than stopping the whole run. Run "index external sources" again any time
|
||||
the source has changed — it refreshes existing entries in place rather
|
||||
than duplicating them, and never deletes a page for a document that's
|
||||
disappeared from the source (it flags it instead, so a later "Lint" pass
|
||||
archives it naturally). Implemented by the `ckb-index-external` skill —
|
||||
`.agents/skills/ckb-index-external/SKILL.md`.
|
||||
|
||||
---
|
||||
|
||||
## 7. What's agent-generated vs. what you can edit
|
||||
|
|
@ -413,7 +472,9 @@ graph stay in sync with what you changed.
|
|||
| `raw/inbox/`, loose files in `raw/` | **You, only** | The agent only reads, archives, and moves things here — it never originates content in `raw/` itself. |
|
||||
| `raw/archive/<date>/` | Agent | Auto-filed copy of what you dropped in `raw/inbox/`, organised by ingestion date. Don't hand-file here — let Ingest do it, so the date and pairing with the log entry stay accurate. |
|
||||
| `linked/<name>/` | **You** (you create the symlink) | Points at another KB's real files, which live and get edited *in that other repo* — never here. The agent must never write inside `linked/`. |
|
||||
| `libs/<name>/` | **You** (you `git clone`) | A frozen copy of an external KB. Update it by re-pulling that repo yourself, not by hand-editing files here. The agent must never write inside `libs/`. |
|
||||
| `libs/<name>/` (git-copy, no `source.yaml`) | **You** (you `git clone`) | A frozen copy of an external KB. Update it by re-pulling that repo yourself, not by hand-editing files here. The agent must never write inside it. |
|
||||
| `libs/<name>/source.yaml` (connector) | **You, only** | Declares the connector and location. The agent reads it but never writes it — same as anything else upstream. |
|
||||
| `libs/<name>/{index.md,entities/,graph/,log.md}` (connector) | Agent-generated, **you can freely edit** | The agent's own index of that one connector's source, built by "Index external sources." Structurally the same deal as the main `wiki/` row below — feel free to correct an entry by hand, then run "Lint" (it now also checks connector-backed indexes). Scoped entirely to that connector; never blended into `wiki/`. |
|
||||
| `wiki/` (pages, `index.md`, `overview.md`, `log.md`, `error-book.md`, `entities/`, `graph/`) | Agent-generated, **you can freely edit** | This is the one place the agent both writes and expects you might too. Feel free to correct a page by hand — just keep the frontmatter fields intact (or update `last_updated`), and run Lint afterward if you touched something the index/graph/log reference. |
|
||||
| `outputs/okf/`, `outputs/starlight/` | Agent, **fully regenerated** | Don't hand-edit — these are gitignored build artifacts, silently overwritten the next time you export. If something's wrong, fix the wiki page it came from and re-export. |
|
||||
| `outputs/teaching/<topic>/` | Agent, semi-persistent state | `plan.md`/`progress.md` the teaching skill reads and writes across sessions. You can look at them any time; hand-editing is possible but may confuse "what's next" tracking — safer to tell the agent what you want changed and let it update the files. |
|
||||
|
|
@ -440,4 +501,5 @@ graph stay in sync with what you changed.
|
|||
| "Export the wiki as OKF" | Machine-readable export at `outputs/okf/` | `ckb-export-okf` |
|
||||
| "Export the wiki to Starlight" | Human-readable docs site at `outputs/starlight/` | `ckb-export-starlight` |
|
||||
| "Upgrade the wiki" / "Check for a newer template version" | Checks template + wiki schema versions against the canonical repo, upgrades what you accept | `ckb-upgrade` |
|
||||
| "Index external sources" / "Index libs" | Builds/refreshes a self-contained index for each connector-backed `libs/<name>/` | `ckb-index-external` |
|
||||
| Just ask a question | Answers from the wiki, using the index/TLDR/graph cascade | — (core query workflow) |
|
||||
|
|
|
|||
76
MANUAL.pl.md
76
MANUAL.pl.md
|
|
@ -56,7 +56,7 @@ nadpisze po cichu istniejącej bazy wiedzy.
|
|||
### Budowanie na bazie cudzej wiki
|
||||
|
||||
Cascade KB może opierać się na jednej lub wielu *nadrzędnych* bazach
|
||||
wiedzy, które pozostają całkowicie tylko do odczytu. Są dwa sposoby ich
|
||||
wiedzy, które pozostają całkowicie tylko do odczytu. Są trzy sposoby ich
|
||||
podpięcia:
|
||||
|
||||
- **Dowiązanie symboliczne** (inna KB na twojej maszynie, lub taka, którą
|
||||
|
|
@ -76,13 +76,30 @@ podpięcia:
|
|||
brak możliwości późniejszego `git pull`, żeby ją odświeżyć — żeby
|
||||
zaktualizować, po prostu pobierz ZIP ponownie i rozpakuj go na starą
|
||||
zawartość.
|
||||
- **Konektor** (żywe zewnętrzne źródło, którego *nie* chcesz mieć w pełnej
|
||||
lokalnej kopii — folder SharePoint, folder Google Drive albo inne
|
||||
podłączone źródło): sam utwórz `libs/<name>/source.yaml`:
|
||||
```yaml
|
||||
connector: sharepoint
|
||||
location: "https://contoso.sharepoint.com/sites/Finance/Shared Documents/Reports"
|
||||
description: "Wspólny folder raportów zespołu finansowego"
|
||||
```
|
||||
a potem powiedz „index external sources". Agent czyta konfigurację,
|
||||
łączy się z tym, co jest dostępne w danej sesji (podłączonym narzędziem
|
||||
Microsoft 365/Google Drive albo zwykłym pobraniem URL), i buduje krótki
|
||||
indeks tego, co znajdzie — po jednym wpisie na dokument — wewnątrz tego
|
||||
samego folderu `libs/<name>/`. Zobacz [§6](#6-przykłady-użycia) po
|
||||
omówiony przykład i to, jak wygląda wynik.
|
||||
|
||||
Niezależnie od sposobu, po podpięciu wystarczy normalnie zadawać pytania —
|
||||
agent sprawdza najpierw twoją lokalną `wiki/`, potem przechodzi przez
|
||||
`linked/`, potem `libs/`, i korzysta z tego, co ma odpowiedź. Nigdy nie
|
||||
edytujesz plików wewnątrz `linked/` ani `libs/` bezpośrednio; jeśli coś tam
|
||||
jest błędne lub nieaktualne, poprawiasz to, zapisując poprawioną wersję we
|
||||
własnej lokalnej `wiki/`, która zawsze wygrywa.
|
||||
edytujesz plików wewnątrz `linked/` ani kopii git w `libs/<name>/`
|
||||
bezpośrednio; jeśli coś tam jest błędne lub nieaktualne, poprawiasz to,
|
||||
zapisując poprawioną wersję we własnej lokalnej `wiki/`, która zawsze
|
||||
wygrywa. (`libs/<name>/` oparty na konektorze to jedyne miejsce, gdzie
|
||||
agent *sam* zapisuje w twoim imieniu — zobacz [§6](#6-przykłady-użycia) —
|
||||
ale nawet tam `source.yaml` pozostaje twój do edycji, nigdy agenta.)
|
||||
|
||||
---
|
||||
|
||||
|
|
@ -413,6 +430,52 @@ W pełni opisane w [§2](#2-dodawanie-wiedzy) — w skrócie: wrzuć materiał d
|
|||
`raw/inbox/` i powiedz „Ingest”, albo po prostu powiedz agentowi w
|
||||
rozmowie, jeśli to wystarczająco krótkie, żeby podać wprost.
|
||||
|
||||
### Indeksowanie zewnętrznego źródła
|
||||
|
||||
Powiedz:
|
||||
|
||||
> „Index external sources.” (lub „index libs”, „refresh the external
|
||||
> index”)
|
||||
|
||||
To przeszukuje każdy `libs/<name>/`, który ma `source.yaml` (zobacz
|
||||
[§1](#budowanie-na-bazie-cudzej-wiki)), i buduje krótki indeks tego, co
|
||||
znajdzie — po jednym wpisie na dokument, plus stronę przeglądową — w
|
||||
całości wewnątrz tego samego folderu `libs/<name>/`. Nic pod `wiki/` nie
|
||||
jest dotykane.
|
||||
|
||||
Przykład:
|
||||
|
||||
> *Tworzysz `libs/finance-reports/source.yaml`:*
|
||||
> ```yaml
|
||||
> connector: sharepoint
|
||||
> location: "https://contoso.sharepoint.com/sites/Finance/Shared Documents/Reports"
|
||||
> description: "Wspólny folder raportów zespołu finansowego"
|
||||
> ```
|
||||
> *potem mówisz „Index external sources.”*
|
||||
>
|
||||
> Agent łączy się, korzystając z tego, co jest dostępne w danej sesji (w
|
||||
> tym przypadku podłączonego narzędzia Microsoft 365), listuje dokumenty w
|
||||
> tym folderze, czyta wystarczająco dużo z każdego, aby napisać krótkie
|
||||
> podsumowanie, i tworzy `libs/finance-reports/index.md` (przegląd źródła)
|
||||
> plus jedną stronę na dokument w `libs/finance-reports/entities/`,
|
||||
> połączone krzyżowo przez `libs/finance-reports/graph/edges.json`. Loguje
|
||||
> wszystko w `libs/finance-reports/log.md` — dzienniku całkowicie
|
||||
> odrębnym od `wiki/log.md`, ponieważ ten indeks jest ograniczony do
|
||||
> jednego konektora, a nie wmieszany w twoją główną wiki. Na koniec
|
||||
> przypomina o przejrzeniu wyniku i powiedzeniu „sync changes”, gdy
|
||||
> będziesz zadowolony.
|
||||
|
||||
Jeśli konektor wymaga autoryzacji (np. połączenie z SharePoint lub Google
|
||||
Drive, które nie jest jeszcze skonfigurowane), agent mówi, który to i gdzie
|
||||
go autoryzować, a potem kontynuuje z innymi skonfigurowanymi źródłami,
|
||||
zamiast zatrzymywać cały przebieg. Uruchom „index external sources”
|
||||
ponownie w każdej chwili, gdy źródło się zmieni — odświeża istniejące
|
||||
wpisy w miejscu, zamiast je duplikować, i nigdy nie usuwa strony dla
|
||||
dokumentu, który zniknął ze źródła (zamiast tego oflagowuje ją, żeby
|
||||
kolejny przebieg „Lint” zarchiwizował ją naturalnie). Zaimplementowane
|
||||
przez skill `ckb-index-external` —
|
||||
`.agents/skills/ckb-index-external/SKILL.md`.
|
||||
|
||||
---
|
||||
|
||||
## 7. Co jest generowane przez agenta, a co możesz edytować
|
||||
|
|
@ -431,7 +494,9 @@ zmieniłeś.
|
|||
| `raw/inbox/`, luźne pliki w `raw/` | **Tylko ty** | Agent tylko czyta, archiwizuje i przenosi rzeczy tutaj — nigdy nie tworzy treści w `raw/` sam. |
|
||||
| `raw/archive/<data>/` | Agent | Automatycznie zarchiwizowana kopia tego, co wrzuciłeś do `raw/inbox/`, uporządkowana według daty ingestu. Nie umieszczaj tu plików ręcznie — pozwól, żeby zrobił to Ingest, tak by data i powiązanie z wpisem w dzienniku były poprawne. |
|
||||
| `linked/<name>/` | **Ty** (tworzysz dowiązanie symboliczne) | Wskazuje na rzeczywiste pliki innej KB, które żyją i są edytowane *w tamtym repozytorium* — nigdy tutaj. Agent nigdy nie może zapisywać wewnątrz `linked/`. |
|
||||
| `libs/<name>/` | **Ty** (robisz `git clone`) | Zamrożona kopia zewnętrznej KB. Aktualizujesz ją, ponownie pobierając to repozytorium samodzielnie, a nie ręcznie edytując pliki tutaj. Agent nigdy nie może zapisywać wewnątrz `libs/`. |
|
||||
| `libs/<name>/` (kopia git, bez `source.yaml`) | **Ty** (robisz `git clone`) | Zamrożona kopia zewnętrznej KB. Aktualizujesz ją, ponownie pobierając to repozytorium samodzielnie, a nie ręcznie edytując pliki tutaj. Agent nigdy nie może zapisywać wewnątrz niej. |
|
||||
| `libs/<name>/source.yaml` (konektor) | **Tylko ty** | Deklaruje konektor i lokalizację. Agent go czyta, ale nigdy nie zapisuje — tak jak wszystko inne nadrzędne. |
|
||||
| `libs/<name>/{index.md,entities/,graph/,log.md}` (konektor) | Generowane przez agenta, **możesz swobodnie edytować** | Własny indeks agenta dla tego jednego źródła konektora, budowany przez „Index external sources”. Strukturalnie ta sama zasada jak przy wierszu `wiki/` poniżej — śmiało popraw wpis ręcznie, a potem uruchom „Lint” (teraz sprawdza też indeksy oparte na konektorach). Ograniczone wyłącznie do tego konektora; nigdy nie wmieszane w `wiki/`. |
|
||||
| `wiki/` (strony, `index.md`, `overview.md`, `log.md`, `error-book.md`, `entities/`, `graph/`) | Generowane przez agenta, **możesz swobodnie edytować** | To jedyne miejsce, w którym zarówno agent zapisuje, jak i spodziewa się, że ty też możesz. Śmiało popraw stronę ręcznie — zachowaj tylko pola frontmatteru (lub zaktualizuj `last_updated`) i uruchom potem Lint, jeśli dotknąłeś czegoś, do czego odwołuje się indeks/graf/dziennik. |
|
||||
| `outputs/okf/`, `outputs/starlight/` | Agent, **w pełni regenerowane** | Nie edytuj ręcznie — to zignorowane przez git artefakty budowania, cicho nadpisywane przy każdym kolejnym eksporcie. Jeśli coś jest nie tak, popraw stronę wiki, z której to pochodzi, i wyeksportuj ponownie. |
|
||||
| `outputs/teaching/<topic>/` | Agent, stan półtrwały | `plan.md`/`progress.md`, które skill do nauczania czyta i zapisuje między sesjami. Możesz je oglądać kiedy chcesz; ręczna edycja jest możliwa, ale może pomieszać śledzenie „co dalej” — bezpieczniej powiedzieć agentowi, co chcesz zmienić, i pozwolić mu zaktualizować pliki. |
|
||||
|
|
@ -458,4 +523,5 @@ zmieniłeś.
|
|||
| „Export the wiki as OKF” | Eksport maszynowy w `outputs/okf/` | `ckb-export-okf` |
|
||||
| „Export the wiki to Starlight” | Czytelna dla człowieka strona dokumentacji w `outputs/starlight/` | `ckb-export-starlight` |
|
||||
| „Upgrade the wiki” / „Check for a newer template version” | Sprawdza wersje szablonu i schematu wiki względem kanonicznego repozytorium, aktualizuje to, co zaakceptujesz | `ckb-upgrade` |
|
||||
| „Index external sources” / „Index libs” | Buduje/odświeża samodzielny indeks dla każdego `libs/<name>/` opartego na konektorze | `ckb-index-external` |
|
||||
| Po prostu zadaj pytanie | Odpowiedź z wiki, przy użyciu kaskady indeks/TLDR/graf | — (podstawowy przepływ zapytań) |
|
||||
|
|
|
|||
50
README.md
50
README.md
|
|
@ -19,7 +19,8 @@ worked examples for every use case — see [MANUAL.md](MANUAL.md)
|
|||
## Directory Structure
|
||||
|
||||
```
|
||||
├── libs/ # Read-only external KBs copied via git (gitignored)
|
||||
├── libs/ # Read-only external sources — git-copy clones (gitignored) OR
|
||||
│ # connector configs (source.yaml) with a self-contained generated index
|
||||
├── linked/ # Read-only upstream KBs mounted as symlinks
|
||||
├── outputs/ # Generated artifacts, exports, compiled files
|
||||
├── raw/ # User-provided source material
|
||||
|
|
@ -46,11 +47,14 @@ When searching, layers are checked in order — first match wins:
|
|||
wiki/ (highest) ← agent writes here, always wins
|
||||
linked/A/ (medium) ← symlinked upstream KBs
|
||||
linked/B/ (low) ← symlinked upstream KBs
|
||||
libs/A/ (lowest) ← git-managed external KB copies
|
||||
libs/A/ (lowest) ← git-managed external KB copies, or a connector's own generated index
|
||||
```
|
||||
|
||||
The agent never writes to `linked/` or `libs/`. To correct upstream content,
|
||||
write the right version in `wiki/` — it takes precedence automatically.
|
||||
The agent never writes to `linked/` or a git-copy `libs/<name>/`. To correct
|
||||
upstream content, write the right version in `wiki/` — it takes precedence
|
||||
automatically. The one exception is a connector-backed `libs/<name>/` (see
|
||||
"External Source Connectors & Indexing" below) — the agent owns and
|
||||
maintains its generated index exactly as it would `wiki/`.
|
||||
|
||||
---
|
||||
|
||||
|
|
@ -124,6 +128,30 @@ full scan. A subdirectory can also keep its own `log.md` once it has enough
|
|||
independent history; `wiki/log.md` stays the root-level rollup and never
|
||||
duplicates a change a subdirectory log already recorded.
|
||||
|
||||
### External Source Connectors & Indexing (on demand)
|
||||
A `libs/<name>/` folder supports a second population mode alongside the
|
||||
existing git-copy one: a small user-authored `libs/<name>/source.yaml`
|
||||
declaring a *live* external source — a SharePoint folder, a Google Drive
|
||||
folder, a plain URL, or another connector — that you don't want to fully
|
||||
mirror locally:
|
||||
```yaml
|
||||
connector: sharepoint
|
||||
location: "https://contoso.sharepoint.com/sites/Finance/Shared Documents/Reports"
|
||||
description: "Finance team's shared reports folder"
|
||||
```
|
||||
Say "index external sources" and the agent walks it, resolving `connector`
|
||||
to whatever live tool is available that session (a connected Microsoft
|
||||
365/Google Drive MCP tool, or `WebFetch` for a plain URL), and builds a
|
||||
self-contained generated index inside that same `libs/<name>/` —
|
||||
`index.md`/`entities/`/`graph/`/`log.md`, mirroring `wiki/`'s own shape via
|
||||
the Recursive Index & Log Convention above, but scoped entirely to that one
|
||||
connector. This is a deliberate design choice: the index is **not** blended
|
||||
into the main `wiki/entities/`/`wiki/graph/edges.json` — it stays separated
|
||||
at the `libs/` cascade layer, the same way a git-cloned KB's own files
|
||||
already are. `source.yaml` itself stays user-only, never written by the
|
||||
agent. Implemented as a Claude Code Skill — see
|
||||
`.agents/skills/ckb-index-external/SKILL.md`.
|
||||
|
||||
### Dual-Linking (Wikilinks + Markdown)
|
||||
Every cross-reference uses both `[[Wikilinks]]` (Obsidian-compatible) and
|
||||
standard `[markdown](path.md)` links. Works in Obsidian graph view, GitHub
|
||||
|
|
@ -283,6 +311,9 @@ advancing. Never writes to `wiki/`. See
|
|||
ln -s /path/to/other-kb ./linked/my-upstream
|
||||
git clone https://github.com/org/external-kb ./libs/external-kb
|
||||
```
|
||||
Or, for a live source you don't want to fully mirror, drop a
|
||||
`libs/<name>/source.yaml` instead (see "External Source Connectors &
|
||||
Indexing" above) and say "index external sources."
|
||||
|
||||
2. **Drop raw material** into `raw/inbox/` (notes, links, articles).
|
||||
|
||||
|
|
@ -313,13 +344,20 @@ copy to keep in sync.
|
|||
|
||||
## Tips
|
||||
|
||||
- Upstream KBs (`linked/` and `libs/`) are **never modified** by agents.
|
||||
- Upstream KBs (`linked/` and git-copy `libs/`) are **never modified** by
|
||||
agents. A connector-backed `libs/<name>/` (one with a `source.yaml`) is
|
||||
the one exception — the agent owns and maintains its generated index.
|
||||
- To correct upstream content, write the correct version in `wiki/` — it wins.
|
||||
- Use `raw/inbox/` for anything unprocessed; the agent clears it on ingest.
|
||||
- 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/` itself is
|
||||
- The `tmp/` directory is gitignored, and so is most of `libs/` — but not
|
||||
all of it: a git-copy `libs/<name>/`'s cloned content stays gitignored as
|
||||
before, while a connector-backed `libs/<name>/`'s `source.yaml` and its
|
||||
generated `index.md`/`entities/`/`graph/`/`log.md` are tracked, since
|
||||
they're synthesized knowledge worth sharing via "sync changes," not a
|
||||
disposable build artifact. `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
|
||||
|
|
|
|||
54
README.pl.md
54
README.pl.md
|
|
@ -20,7 +20,8 @@ znajdziesz w [MANUAL.pl.md](MANUAL.pl.md) ([English](MANUAL.md)).
|
|||
## Struktura katalogów
|
||||
|
||||
```
|
||||
├── libs/ # Zewnętrzne bazy wiedzy tylko do odczytu, kopiowane przez git (w .gitignore)
|
||||
├── libs/ # Zewnętrzne źródła tylko do odczytu — kopie git (w .gitignore) LUB
|
||||
│ # konfiguracje konektora (source.yaml) z własnym generowanym indeksem
|
||||
├── linked/ # Zewnętrzne bazy wiedzy tylko do odczytu, montowane jako dowiązania symboliczne
|
||||
├── outputs/ # Wygenerowane artefakty, eksporty, skompilowane pliki
|
||||
├── raw/ # Materiał źródłowy dostarczony przez użytkownika
|
||||
|
|
@ -48,12 +49,14 @@ wygrywa:
|
|||
wiki/ (najwyższy) ← agent zapisuje tutaj, zawsze wygrywa
|
||||
linked/A/ (średni) ← zamontowane przez symlink wiki nadrzędne
|
||||
linked/B/ (niski) ← zamontowane przez symlink wiki nadrzędne
|
||||
libs/A/ (najniższy) ← kopie zewnętrznych baz wiedzy zarządzane przez git
|
||||
libs/A/ (najniższy) ← kopie zewnętrznych baz wiedzy zarządzane przez git, albo własny generowany indeks konektora
|
||||
```
|
||||
|
||||
Agent nigdy nie zapisuje do `linked/` ani `libs/`. Aby poprawić treść
|
||||
nadrzędną, zapisz właściwą wersję w `wiki/` — automatycznie zyskuje
|
||||
pierwszeństwo.
|
||||
Agent nigdy nie zapisuje do `linked/` ani do `libs/<name>/` będącego kopią
|
||||
git. Aby poprawić treść nadrzędną, zapisz właściwą wersję w `wiki/` —
|
||||
automatycznie zyskuje pierwszeństwo. Jedynym wyjątkiem jest `libs/<name>/`
|
||||
oparty na konektorze (zobacz „Konektory zewnętrznych źródeł i indeksowanie”
|
||||
poniżej) — agent zarządza jego generowanym indeksem tak samo, jak `wiki/`.
|
||||
|
||||
---
|
||||
|
||||
|
|
@ -139,6 +142,30 @@ własny `log.md`, gdy ma już wystarczająco dużo niezależnej historii;
|
|||
`wiki/log.md` pozostaje rollupem na poziomie głównym i nigdy nie powtarza
|
||||
zmiany już zapisanej w dzienniku podkatalogu.
|
||||
|
||||
### Konektory zewnętrznych źródeł i indeksowanie (na żądanie)
|
||||
Folder `libs/<name>/` obsługuje drugi sposób zasilania, obok istniejącej
|
||||
kopii git: mały, autorski plik `libs/<name>/source.yaml`, który deklaruje
|
||||
*żywe* zewnętrzne źródło — folder SharePoint, folder Google Drive, zwykły
|
||||
URL albo inny konektor — którego nie chcesz w pełni kopiować lokalnie:
|
||||
```yaml
|
||||
connector: sharepoint
|
||||
location: "https://contoso.sharepoint.com/sites/Finance/Shared Documents/Reports"
|
||||
description: "Wspólny folder raportów zespołu finansowego"
|
||||
```
|
||||
Powiedz „index external sources", a agent go przeskanuje, dopasowując
|
||||
`connector` do dowolnego żywego narzędzia dostępnego w danej sesji
|
||||
(połączonego narzędzia MCP do Microsoft 365/Google Drive, albo `WebFetch`
|
||||
dla zwykłego adresu URL), i zbuduje samodzielny, generowany indeks wewnątrz
|
||||
tego samego `libs/<name>/` — `index.md`/`entities/`/`graph/`/`log.md`,
|
||||
odzwierciedlający strukturę `wiki/` opisaną w Rekurencyjnej konwencji
|
||||
indeksu i dziennika powyżej, ale ograniczony wyłącznie do tego jednego
|
||||
konektora. To celowa decyzja projektowa: ten indeks **nie** jest wmieszany
|
||||
w główne `wiki/entities/`/`wiki/graph/edges.json` — pozostaje oddzielony na
|
||||
warstwie kaskady `libs/`, tak samo jak pliki sklonowanej przez git KB. Sam
|
||||
`source.yaml` pozostaje wyłącznie twój, agent nigdy go nie zapisuje.
|
||||
Zaimplementowane jako Claude Code Skill — zobacz
|
||||
`.agents/skills/ckb-index-external/SKILL.md`.
|
||||
|
||||
### Podwójne linkowanie (Wikilinks + Markdown)
|
||||
Każde odwołanie krzyżowe używa zarówno `[[Wikilinks]]` (kompatybilnych z
|
||||
Obsidian), jak i standardowych linków `[markdown](path.md)`. Działa w
|
||||
|
|
@ -326,6 +353,10 @@ słabe punkty przed przejściem dalej. Nigdy nie zapisuje do `wiki/`. Zobacz
|
|||
ln -s /path/to/other-kb ./linked/my-upstream
|
||||
git clone https://github.com/org/external-kb ./libs/external-kb
|
||||
```
|
||||
Albo, dla żywego źródła, którego nie chcesz w pełni kopiować lokalnie,
|
||||
umieść zamiast tego `libs/<name>/source.yaml` (zobacz „Konektory
|
||||
zewnętrznych źródeł i indeksowanie" powyżej) i powiedz „index external
|
||||
sources".
|
||||
|
||||
2. **Wrzuć surowy materiał** do `raw/inbox/` (notatki, linki, artykuły).
|
||||
|
||||
|
|
@ -357,8 +388,10 @@ synchronizacji.
|
|||
|
||||
## Wskazówki
|
||||
|
||||
- Nadrzędne bazy wiedzy (`linked/` i `libs/`) **nigdy nie są modyfikowane**
|
||||
przez agentów.
|
||||
- Nadrzędne bazy wiedzy (`linked/` i kopie git w `libs/`) **nigdy nie są
|
||||
modyfikowane** przez agentów. Wyjątkiem jest `libs/<name>/` oparty na
|
||||
konektorze (ten z `source.yaml`) — agent zarządza jego generowanym
|
||||
indeksem.
|
||||
- Aby poprawić treść nadrzędną, zapisz poprawną wersję w `wiki/` — ona
|
||||
wygrywa.
|
||||
- Używaj `raw/inbox/` dla wszystkiego, co nieprzetworzone; agent czyści ją
|
||||
|
|
@ -367,7 +400,12 @@ synchronizacji.
|
|||
bieżąco.
|
||||
- Confidence, quality i freshness pozwalają ufać właściwej treści i
|
||||
oflagowywać resztę do przeglądu.
|
||||
- Katalogi `tmp/` i `libs/` są w `.gitignore`. Sam `outputs/` jest śledzony,
|
||||
- Katalog `tmp/` jest w `.gitignore`, podobnie jak większość `libs/` — ale
|
||||
nie cały: zawartość kopii git w `libs/<name>/` pozostaje w `.gitignore`
|
||||
jak dawniej, natomiast `source.yaml` konektora i jego generowany
|
||||
`index.md`/`entities/`/`graph/`/`log.md` są śledzone, ponieważ to
|
||||
zsyntetyzowana wiedza warta udostępnienia przez „sync changes", a nie
|
||||
jednorazowy artefakt budowania. Sam `outputs/` jest śledzony,
|
||||
ale jego regenerowalne podkatalogi budowania, `outputs/okf/` i
|
||||
`outputs/starlight/`, są w `.gitignore` — każdy z nich jest w pełni
|
||||
odtwarzalny z `wiki/` na żądanie, więc nie ma czego uzgadniać, przenosząc
|
||||
|
|
|
|||
2
VERSION
2
VERSION
|
|
@ -1 +1 @@
|
|||
1.0.0
|
||||
1.1.0
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue