bcos-wiki

/wiki

See also: context-ingest is the single public entry point for new material. If the user dropped raw content of unknown shape ("here's a doc", "save this"), prefer context-ingest — it dispatches here automatically when the input is a URL or an _inbox/ capture. Use /wiki directly only when the user explicitly names the wiki (/wiki run, "promote to wiki", "add to the wiki").

What this skill stores

The wiki is BCOS's universal long-form / cross-cutting content destination — canonical per [plugin-storage-contract.md](../../../docs/_bcos-framework/architecture/plugin-storage-contract.md) Rule 2. Anything operational or explanatory that isn't a canonical data point and isn't legal-weight evidence lives here. That includes:

• Operational truth (authority: canonical-process) — runbooks, SOPs, how-tos, decision logs, post-mortems, playbooks, tutorials, scripts-with-context
• Internal reference (authority: internal-reference) — glossaries, FAQs, internal explainers
• Plugin cross-cutting content — charters, meeting transcripts, WhatsApp / Slack exports, email captures, customer-call notes, research clippings (Rule 2 worked examples)
• External sources (authority: external-reference) — captured URLs / GitHub repos / YouTube transcripts via Path A, with banner citations to the verbatim raw capture

Routes all of the above into docs/_wiki/ as first-class managed documents: schema-validated frontmatter, derived index.md, BCOS-compatible CLEAR ownership, builds-on graph for cross-references, two-tier refresh for staying current, supersedes chains for temporal succession.

What does NOT belong here: canonical data points (those live in docs/*.md); legal-weight evidence (signed contracts, regulatory filings → _collections/); plugin-private structured records (those live in docs/_<plugin>/ per Rule 1).

Trigger phrases

• /wiki with subcommands: init, init --defaults, run, queue, promote, create, review, archive, refresh, lint, remove, schema, search
• "Add this URL to the wiki"
• "Promote this _inbox/ capture into a wiki page"
• "Store this runbook / SOP / decision log / transcript in the wiki" (Path B)
• "Ingest this PDF as a wiki source-summary"
• "Run the wiki refresh"
• "Initialize the wiki zone" (interactive) or "scaffold the wiki with defaults" (headless --defaults)

Pipeline at a glance

Two ingest paths converge on the same schema-validated wiki page. Path B (local content) is the common case for operational/explanatory knowledge; Path A (URLs) handles external sources.

PATH B — local content                          PATH A — external URLs
(runbooks, SOPs, decision logs,                 (web articles, GitHub repos,
 transcripts, scripts, notes, …)                 YouTube transcripts)

/wiki create from <path-or-paste>               queue.md  (URLs, human-curated)
/wiki promote docs/_inbox/<file>.md                  ↓  fetch (web | github | youtube)
        ↓                                       docs/_wiki/raw/<type>/  (immutable)
docs/_wiki/raw/local/<slug>.md                       ↓
(+ binary <slug>.<ext> if PDF/.docx)            docs/_wiki/source-summary/<slug>.md
        ↓                                       (3 structural shapes: standalone,
docs/_wiki/pages/<slug>.md                       unified, umbrella+sub)
(page-type: how-to | runbook | decision-log |
 post-mortem | glossary | faq | playbook |               ↓
 tutorial | meeting-notes | …)                  banner citation: raw/<type>/<slug>.md

        ↘                                       ↙
         schema-validated frontmatter, builds-on graph,
         provenance, authority value, supersedes chain
                          ↓
                  refresh_wiki_index.py
                          ↓
              docs/_wiki/index.md (derived)

The two paths produce the same wiki page format. Page-type is in the frontmatter, not in the folder layout. The difference is just origin: Path B from local content (with a provenance: block recording the source); Path A from external URLs (with source-url, last-fetched, detail-level and one of three structural shapes).

Subcommands

| Command | Status | Phase | What it does | |---|---|---|---| | init | implemented | P3 | Scaffold docs/_wiki/ (config + schema + page templates + queue + log + overview); never overwrite. Interactive — 6-question AskUserQuestion interview. | | init --defaults | implemented | P3 | Headless scaffold with sensible defaults (display_name = git repo basename; detail_level=standard; source_types=[web,github,youtube]; auto_lint=batch; auto_mark_complete=true; enable_path_b=true). Delegates to [cmd_wiki_init.py](../../scripts/cmd_wiki_init.py). Idempotent — no-op on existing zone. Used by the Guard's auto-init flow and by ensure_wiki_zone.py for plugin installs. | | run [<url>] | implemented | P3 | Path A: batch (no arg) processes all ## Pending queue items; single (with URL) auto-queues + ingests | | queue <url> [tags] | implemented | P3 | Append URL to ## Pending of queue.md without fetching | | ingest | shared protocol | P3 | Internal — called by run/promote/create; shared pipeline. Not a user-facing entry | | promote <inbox-path> | implemented | P3 | Path B: convert an _inbox/ capture into a wiki page; provenance.kind = inbox-promotion | | create from <path-or-paste> | implemented | P3 | Path B: ingest a local file or pasted text; provenance.kind = local-document | | review <slug> | implemented | P3 | Bump last-reviewed; optionally re-pull builds-on data points to verify | | archive <slug> | implemented | P3 | Soft-delete to _wiki/.archive/ with dangling-reference scan | | refresh <slug> | implemented | P3 | Path A: re-fetch a source-summary page (refresh-must-rediscover applies, D-05 two-tier) | | lint | implemented | P3 | Run wiki-specific lint checks on demand (also runs via daily/scheduled jobs) | | remove <slug> | implemented | P3 | Hard remove (vs archive soft-delete) — only when the user explicitly wants the page+raw gone | | schema list\|add\|rename\|retire\|validate\|migrate | P4 | Vocabulary governance — see schema.md (P4) | | search <query> | implemented | P2 | Zone-scoped sugar over /context search --zone wiki (mechanical BM25; --semantic opt-in only) — see search.md | | 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 |

Dispatch

1. Identify the subcommand from the first word after /wiki.
2. Guard (every subcommand except init): confirm docs/_wiki/.config.yml exists. If missing, follow the Guard — auto-init flow below. Subcommand files repeat this guard by reference; you only enforce it once per invocation.
3. Route — read the sibling file in this skill directory and follow its instructions:
4. init → init.md (no Guard)
5. run → run.md
6. queue → queue.md
7. promote → promote.md
8. create → create.md
9. review → review.md
10. archive → archive.md
11. refresh → refresh.md
12. lint → lint.md
13. remove → remove.md
14. schema → schema.md (P4)
15. search → search.md (P2; zone-scoped sugar over /context search)
16. bundle → bundle.md (P5; zone-scoped sugar over /context bundle)
17. Do not proceed past dispatch before reading the target file.

Guard — auto-init flow (when _wiki/.config.yml is missing)

The pre-2026-05-13 behavior was a hard-stop: print "No wiki zone here. Run /wiki init first." and exit. That created a dead-end for downstream agents (observed in a downstream session) — agents would fall back to writing operational content into docs/operations/ instead of the wiki. The current behavior turns the guard into a structured choice while preserving the hard-stop sema