Bcos Wiki

1---
2name: bcos-wiki
3description: "Wiki zone manager for BCOS. Ingests URLs / local docs / inbox captures into docs/_wiki/ as schema-validated pages with banner citations, three structural shapes for source-summary, and two-tier refresh. Schema-driven, CLEAR-governed, derived-artifact. Invoke with /wiki."
4trigger: "/wiki"
5version: "1.0.0"
6last_updated: "2026-05-02"
7authority-docs:
8  - docs/_bcos-framework/architecture/wiki-zone.md
9  - docs/_bcos-framework/templates/_wiki.schema.yml.tmpl
10  - docs/_planned/wiki-zone-integration/pre-flight-decisions.md
11---
12 
13# /wiki
14 
15Wiki-zone manager for BCOS. Routes URL ingests, local-document promotions, and inbox captures into `docs/_wiki/` as first-class managed documents (schema-validated frontmatter, derived `index.md`, BCOS-compatible CLEAR ownership).
16 
17## Trigger phrases
18 
19- **`/wiki`** with subcommands: `init`, `run`, `queue`, `promote`, `create`, `review`, `archive`, `refresh`, `lint`, `remove`, `schema`, `search`
20- "Add this URL to the wiki"
21- "Promote this `_inbox/` capture into a wiki page"
22- "Ingest this PDF as a wiki source-summary"
23- "Run the wiki refresh"
24- "Initialize the wiki zone"
25 
26## Pipeline at a glance
27 
28```
29queue.md (URLs, human-curated)
30    ↓  fetch (web | github | youtube)            ← Path A
31docs/_wiki/raw/<type>/  (immutable captures)
32    ↓  ingest (banner citation; 3 shapes)
33docs/_wiki/source-summary/<slug>.md  ← schema-validated
34                                  ↓
35                              refresh_wiki_index.py (derived index)
36 
37 
38/wiki promote docs/_inbox/<file>.md          ← Path B (inbox-promotion)
39/wiki create from <path-or-paste>            ← Path B (local-document)
40    ↓
41docs/_wiki/raw/local/<slug>.<ext>            (binaries) + .md (extraction)
42    ↓
43docs/_wiki/pages/<slug>.md                   ← provenance frontmatter
44                                  ↓
45                              refresh_wiki_index.py
46```
47 
48## Subcommands
49 
50| Command | Status | Phase | What it does |
51|---|---|---|---|
52| `init` | implemented | P3 | Scaffold `docs/_wiki/` (config + schema + page templates + queue + log + overview); never overwrite |
53| `run [<url>]` | implemented | P3 | Path A: batch (no arg) processes all `## Pending` queue items; single (with URL) auto-queues + ingests |
54| `queue <url> [tags]` | implemented | P3 | Append URL to `## Pending` of `queue.md` without fetching |
55| `ingest` | shared protocol | P3 | Internal — called by `run`/`promote`/`create`; shared pipeline. Not a user-facing entry |
56| `promote <inbox-path>` | implemented | P3 | Path B: convert an `_inbox/` capture into a wiki page; provenance.kind = inbox-promotion |
57| `create from <path-or-paste>` | implemented | P3 | Path B: ingest a local file or pasted text; provenance.kind = local-document |
58| `review <slug>` | implemented | P3 | Bump `last-reviewed`; optionally re-pull `builds-on` data points to verify |
59| `archive <slug>` | implemented | P3 | Soft-delete to `_wiki/.archive/` with dangling-reference scan |
60| `refresh <slug>` | implemented | P3 | Path A: re-fetch a `source-summary` page (refresh-must-rediscover applies, D-05 two-tier) |
61| `lint` | implemented | P3 | Run wiki-specific lint checks on demand (also runs via daily/scheduled jobs) |
62| `remove <slug>` | implemented | P3 | Hard remove (vs `archive` soft-delete) — only when the user explicitly wants the page+raw gone |
63| `schema list\|add\|rename\|retire\|validate\|migrate` | P4 | Vocabulary governance — see `schema.md` (P4) |
64| `search <query>` | implemented | P2 | Zone-scoped sugar over `/context search --zone wiki` (mechanical BM25; `--semantic` opt-in only) — see `search.md` |
65| `bundle <profile>` | implemented | P5 | Zone-scoped sugar over `/context bundle <profile>` (mechanical task-driven routing; `--resolve-conflicts` / `--verify-coverage` opt-in only) — see `bundle.md` |
66 
67## Dispatch
68 
691. Identify the subcommand from the first word after `/wiki`.
702. **Guard (every subcommand except `init`):** confirm `docs/_wiki/.config.yml` exists. If missing, stop with:
71   > *"No wiki zone here (`docs/_wiki/.config.yml` missing). Run `/wiki init` to scaffold one first."*
72   Subcommand files repeat this guard by reference; you only enforce it once per invocation.
733. Route — read the sibling file in this skill directory and follow its instructions:
74   - `init` → `init.md` (no Guard)
75   - `run` → `run.md`
76   - `queue` → `queue.md`
77   - `promote` → `promote.md`
78   - `create` → `create.md`
79   - `review` → `review.md`
80   - `archive` → `archive.md`
81   - `refresh` → `refresh.md`
82   - `lint` → `lint.md`
83   - `remove` → `remove.md`
84   - `schema` → `schema.md` (P4)
85   - `search` → `search.md` (P2; zone-scoped sugar over `/context search`)
86   - `bundle` → `bundle.md` (P5; zone-scoped sugar over `/context bundle`)
874. Do not proceed past dispatch before reading the target file.
88 
89## Guard rails (universal — apply to every subcommand)
90 
91### Git policy (canonical)
92 
93**Never run `git commit` or `git push`** after `init`, `run`, `ingest`, `promote`, `create`, `review`, `archive`, `refresh`, `lint`, `remove`, or `schema` — unless the human explicitly asked to commit in this conversation. List what changed and stop. The human reviews diffs and runs `git commit` / `git push` when ready.
94 
95This matches BCOS's broader convention (see `docs/.session-diary.md` and `CLAUDE.md`'s "Auto-commit" policy).
96 
97### Frontmatter discipline (D-04)
98 
99Every wiki page satisfies BCOS's standard required fields **plus** the wiki extensions defined in `_wiki/.schema.yml`. The PostToolUse hook validates this on every save and emits these IDs on violation: `schema-violation`, `reference-format-mismatch`, `forbidden-builds-on-target`, `provenance-required`, `shape-conflict`, `folder-mismatch`, `schema-version-drift`.
100 
101**Reference-format rule** (slugs intra-zone, paths cross-zone):
102- `references:`, `subpages:`, `parent-slug:`, body `[[...]]` → bare slug, no `.md`
103- `builds-on:`, `raw-files:`, body `[text](../path.md)` → relative path with `.md`
104 
105### Derived artifacts (D-11)
106 
107- `docs/_wiki/index.md` — regenerated by `.claude/scripts/refresh_wiki_index.py`. **Never hand-edit.** All ingest subcommands call this script as their final step.
108- `docs/_wiki/log.md` — append-only. Only ingest/refresh/remove/archive may add entries; never rewrite.
109- `docs/_wiki/overview.md` — authored prose. Updated by `ingest` (one paragraph per source-summary, in `sources:` order).
110 
111### Token guard (D-05)
112 
113Any single fetch projected to exceed **200,000 tokens** halts and asks the user to confirm or downgrade `detail-level`. This applies to `run`, `refresh`, and `create` (when source content is large).
114 
115### Path B writes never cross zones (D-06)
116 
117`promote` and `create` keep binaries in `docs/_wiki/raw/local/<slug>.<ext>` alongside their markdown extraction. They do **not** write to `docs/_collections/`. Users who want a binary in collections-as-evidence must run `/collections add` explicitly.
118 
119### Cluster permissive default (D-03)
120 
121When `_wiki/.schema.yml` has `clusters.allow-cluster-not-in-source: true` (v1 default), wiki pages may declare a `cluster:` not yet in `docs/document-index.md` — drift surfaces via the quarterly `wiki-coverage-audit` as INFO, not ERROR. Tighten to `false` only after the cluster-mint follow-up (`FU_006`) lands.
122 
123## File layout (in this skill)
124 
125```
126.claude/skills/bcos-wiki/
127├── SKILL.md                ← this file
128├── init.md                 ← /wiki init
129├── run.md                  ← /wiki run [<url>]
130├── ingest.md               ← shared ingest pipeline (called by run/promote/create/refresh)
131├── queue.md                ← /wiki queue
132├── promote.md              ← /wiki promote
133├── create.md               ← /wiki create from
134├── review.md               ← /wiki review
135├── archive.md              ← /wiki archive
136├── refresh.md              ← /wiki refresh
137├── lint.md                 ← /wiki lint
138├── remove.md               ← /wiki remove
139├── schema.md               ← /wiki schema  (P4)
140├── references/
141│   └── migration-helpers.md   ← schema-version migration recipes (P4)
142├── templates/
143│   ├── protocols/
144│   │   ├── common.md       ← URL parsing, slug derivation, inbox-tag DSL
145│   │   ├── web.md
146│   │   ├── github.md
147│   │   ├── youtube.md
148│   │   └── local.md        ← Path B: binary handling, hash, extraction
149│   ├── page-types/
150│   │   ├── how-to.md
151│   │   ├── glossary.md
152│   │   └── source-summary.md
153│   ├── raw/
154│   │   ├── web-README.md.tmpl
155│   │   ├── github-README.md.tmpl
156│   │   ├── youtube-README.md.tmpl
157│   │   └── local-README.md.tmpl
158│   ├── queue.md.tmpl
159│   ├── overview.md.tmpl
160│   ├── log.md.tmpl
161│   └── README.md.tmpl
162```
163 
164`templates/page-types/` are starter bodies for each registered `page-type`. New types added via `/wiki schema add page-type <name>` get a stub auto-created.
165 
166## What the skill does NOT do
167 
168- Write data points (those live in `docs/*.md` — use `context-ingest` and the data-point template)
169- Touch `docs/_collections/` (evidence zone — explicit user actions only, see D-06)
170- Cross-tool adapter manuals (`AGENTS.md`-style) — BCOS uses one `CLAUDE.md`
171- Auto-commit or auto-push (see Git policy above)
172 
173## See also
174 
175- `docs/_bcos-framework/architecture/wiki-zone.md` — full architecture spec
176- `docs/_bcos-framework/templates/_wiki.schema.yml.tmpl` — vocabulary registry
177- `docs/_planned/wiki-zone-integration/pre-flight-decisions.md` — D-01 → D-11 decision rationale
178