docs(skill): tighten references, fix marketplace spec, add per-CLI install

Three rounds of cleanup driven by review feedback:

1. **`.openkb/` internal state hidden from references**
   `wiki-schema.md` previously detailed `config.yaml`, `hashes.json`,
   and `pageindex.db` schemas in the directory tree — inviting agents
   to bypass the public `openkb status` / `openkb list` interface and
   couple to internal storage that may change. Replaced with a single
   line: "Internal openkb state lives at `<kb-root>/.openkb/`. **Do
   not read these directly** — use `openkb status` / `openkb list`."

2. **References trimmed (~33% smaller, more focused)**
   - `commands.md` 3.1KB → 2.2KB: dropped verbose example outputs
     (full multi-line `openkb list`, `openkb status`, `openkb query`
     captures) in favor of minimal shape examples. Merged the
     "NOT typically needed" + "Write commands — DO NOT run" sections
     so the agent has one clear safety list.
   - `wiki-schema.md` 5.7KB → 3.7KB: dropped the `.openkb/` subtree
     and the full `hashes.json` schema (internal). Trimmed long
     directory tree to category lines only. Kept the frontmatter
     YAML examples since those ARE the contract.

3. **`marketplace.json` polished per Claude Code spec**
   - Renamed top-level `name: "openkb"` → `name: "openkb-marketplace"`
     so users type `/plugin install openkb@openkb-marketplace` instead
     of the awkward `openkb@openkb`. Mirrors Anthropic's pattern
     (marketplace `anthropic-agent-skills`, plugin `document-skills`).
   - Swapped `owner.url` for `owner.email` (the idiomatic field).
   - Added `version`, `author`, `homepage`, `repository`, `license`,
     `keywords` on the plugin entry. None required by spec but all
     low-effort polish that helps discovery.

4. **README install section now per-CLI**
   Three separate snippets:
   - Claude Code: `/plugin marketplace add VectifyAI/OpenKB` then
     `/plugin install openkb@openkb-marketplace`.
   - Gemini CLI: `gemini skills install <repo> --path skills/openkb`
     — native installer reads our `skills/` tree directly.
   - Codex CLI: manual `git clone` + symlink into `~/.agents/skills/`.
     Codex has no marketplace mechanism today; `.agents/skills/` is
     its discovery path. Once a Codex marketplace ships, the same
     `marketplace.json` will likely work.

Author: KylinMountain

.claude-plugin/marketplace.json

@@ -1,8 +1,8 @@
 {
-  "name": "openkb",
+  "name": "openkb-marketplace",
   "owner": {
     "name": "VectifyAI",
-    "url": "https://github.com/VectifyAI/OpenKB"
+    "email": "team@vectify.ai"
   },
   "metadata": {
     "description": "Skills for navigating an OpenKB-compiled knowledge base from agent CLIs (Claude Code, Codex, Gemini CLI).",
@@ -14,6 +14,15 @@
       "description": "Navigate an OpenKB-compiled wiki: discover documents and concepts via openkb CLI commands, read concept and summary pages directly, and follow wikilinks across the knowledge graph.",
       "source": "./",
       "strict": false,
+      "version": "0.1.0",
+      "author": {
+        "name": "VectifyAI",
+        "email": "team@vectify.ai"
+      },
+      "homepage": "https://github.com/VectifyAI/OpenKB",
+      "repository": "https://github.com/VectifyAI/OpenKB",
+      "license": "Apache-2.0",
+      "keywords": ["knowledge-base", "wiki", "openkb", "rag", "agent-skill"],
       "skills": [
         "./skills/openkb"
       ]

README.md

@@ -240,18 +240,30 @@ OpenKB's wiki is a directory of Markdown files with `[[wikilinks]]`. Obsidian re
 
 OpenKB ships a [SKILL.md](https://agentskills.io/) so any agent CLI can read your compiled wiki — no extra runtime, no MCP setup, just install the skill once.
 
-```bash
-# Claude Code
+**Claude Code** (via the plugin marketplace):
+
+```
 /plugin marketplace add VectifyAI/OpenKB
-/plugin install openkb@openkb
+/plugin install openkb@openkb-marketplace
+```
+
+**Gemini CLI** (native skills installer):
 
-# Cross-tool (works for Codex / Cursor / Cline / Gemini CLI too)
-npx skills@latest add VectifyAI/OpenKB
+```bash
+gemini skills install https://github.com/VectifyAI/OpenKB.git --path skills/openkb --consent
+```
+
+**OpenAI Codex CLI** (no marketplace yet — manual install):
+
+```bash
+git clone https://github.com/VectifyAI/OpenKB.git ~/openkb-src
+mkdir -p ~/.agents/skills
+ln -s ~/openkb-src/skills/openkb ~/.agents/skills/openkb
 ```
 
-After install, when the agent's working directory contains a `.openkb/` folder and `wiki/` tree, the skill activates automatically — the agent will use `openkb list`, `openkb status`, and `openkb query` for catalog and synthesis, and read concept/summary pages directly from `wiki/` for raw content.
+(Codex discovers skills under `.agents/skills/` walking up from cwd, or `~/.agents/skills/` for user-scope.)
 
-The skill is read-only: it won't run `openkb add`, `remove`, or `lint --fix` without you asking. See [`skills/openkb/SKILL.md`](skills/openkb/SKILL.md) for the full instruction set the agent receives.
+After install, when the user asks about content in their OpenKB knowledge base, the skill activates and points the agent at `openkb status` to discover the KB, `openkb list` for the catalog, and direct Markdown reads for concept/summary content. The skill is read-only: it won't run `openkb add`, `remove`, or `lint --fix` without you asking. See [`skills/openkb/SKILL.md`](skills/openkb/SKILL.md) for the full instruction set the agent receives.
 
 # 🧭 Learn More
 

skills/openkb/references/commands.md

@@ -1,122 +1,69 @@
-# OpenKB CLI command reference
+# OpenKB CLI reference
 
-Only the commands relevant to **reading** an OpenKB knowledge base
-are listed here. Write commands (`add`, `remove`, `lint --fix`, etc.)
-should be suggested to the user, not run autonomously by the agent.
-
-## `openkb list`
-
-List ingested documents and their compiled concepts.
-
-```
-$ openkb list
-Documents (2):
-  Name                                     Type         Pages
-  ---------------------------------------- ------------ --------
-  paper.pdf                                pageindex    42
-  notes.md                                 short
-
-Summaries (2):
-  - paper
-  - notes
-
-Concepts (5):
-  - attention
-  - transformer
-  - positional-encoding
-  - self-attention
-  - multi-head-attention
-```
-
-- `Type` is the *display* form of the registry's `type` field, mapped
-  through `_TYPE_DISPLAY_MAP`:
-    - PageIndex-indexed long PDFs (registry `type: long_pdf`) display
-      as `pageindex`.
-    - Every other format (`md`, `docx`, `pdf` short, `txt`, …) displays
-      as `short`.
-  The raw registry value lives in `.openkb/hashes.json`; the displayed
-  value is what surfaces in `openkb list` and in `index.md` type tags
-  (`(short)` / `(pageindex)`).
-- `Pages` only populated for long PDFs.
-- The Summaries and Concepts lists are simply directory listings of
-  `wiki/summaries/` and `wiki/concepts/` minus their `.md` suffix.
+Read commands the skill calls on. Write commands are listed at the
+bottom — the agent MUST NOT run them autonomously.
 
 ## `openkb status`
 
-Knowledge base overview. **Always run this first** when working with
-an OpenKB KB — its first line tells you where the KB lives, which is
-what you need for every `Read` / `Grep` / `jq` call afterwards.
+KB overview. First line carries the absolute path of the active KB
+— parse it before any file read:
 
 ```
 $ openkb status
 Knowledge base: /path/to/kb
-
 Knowledge Base Status:
-  Directory            Files
-  -------------------- ----------
-  sources              5
-  summaries            5
-  concepts             12
-  reports              2
-  raw                  5
-
-  Total indexed: 5 document(s)
-  Last compile:  2026-05-16 12:14:12
-  Last lint:     2026-05-16 12:16:31
+  ...directory counts and timestamps...
 ```
 
-- The `Knowledge base: <path>` line is parseable: it's the absolute
-  path of the active KB. The user may have invoked you from anywhere
-  — never assume cwd is the KB root; use this path.
-- Resolution: walks up from cwd looking for `.openkb/`, then falls
-  back to the global default set by `openkb use`.
-- Empty case: prints "No knowledge base found. Run `openkb init`
-  first." Tell the user this and stop — don't try to read files.
+Resolution: walks up from cwd, then falls back to `openkb use`'s
+global default. Empty case prints "No knowledge base found. Run
+`openkb init` first." — stop and tell the user; don't try to read.
 
-## `openkb query "<question>"`
+## `openkb list`
 
-Run a full retrieval-augmented query against the wiki. Returns a
-synthesized answer with citations. **Costs an LLM call inside
-OpenKB**, so use this when the user explicitly wants a synthesized
-answer across the whole KB, not for simple lookups that can be
-answered by reading directly.
+Documents + concepts table. `Type` is mapped via `_TYPE_DISPLAY_MAP`:
+long PDFs show as `pageindex`, everything else as `short` (the raw
+file extension is internal and not exposed). `Pages` only populated
+for long PDFs.
 
 ```
-$ openkb query "How does self-attention scale with sequence length?"
-Self-attention is O(n²) in sequence length because every token attends
-to every other token...
-
-Sources:
-- [[concepts/self-attention]]
-- [[summaries/transformers]] (sources/transformers.md)
+$ openkb list
+Documents (N):
+  Name              Type        Pages
+  paper.pdf         pageindex   42
+  notes.md          short
+Summaries (N):
+  - paper
+Concepts (N):
+  - attention
 ```
 
-Add `--save` to persist the answer at
-`wiki/explorations/<slug>.md` — but only when the user asks for it.
+## `openkb query "<question>"`
+
+Full RAG pipeline — costs an LLM call inside openkb. Use only when
+no obvious slug matches and direct reads can't answer. Returns
+free-form answer text plus cited `[[concepts/...]]` / `[[summaries/...]]`
+paths. Add `--save` to persist to `wiki/explorations/<slug>.md` —
+only when the user asks for it.
 
-## Read-only commands NOT typically needed from a skill
+## Read-only commands the skill should NOT call
 
-- `openkb chat` — interactive REPL, not appropriate for skill usage
-- `openkb watch` — daemon for auto-ingesting from `raw/`
-- `openkb lint` — health check; produces a report file. Don't run
-  unless the user explicitly asks about wiki health.
+- `openkb chat` — interactive REPL
+- `openkb watch` — daemon
+- `openkb lint` — health-check report (run only if the user
+  explicitly asks about wiki health)
 
-## Write commands — DO NOT run autonomously
+## Write commands — MUST NOT run autonomously
 
-These mutate the user's knowledge base:
+These mutate the user's knowledge base. Suggest with a one-line
+description of what they do; let the user run them:
 
-- `openkb add <path>` — ingest a new document (LLM cost)
+- `openkb add <path>` — ingest a document (LLM cost, modifies wiki)
 - `openkb remove <doc>` — destructive removal
 - `openkb lint --fix` — auto-edits wiki pages
-- `openkb init` — one-time setup
-- `openkb use <path>` — sets the default KB
-
-Suggest these to the user with a sentence explaining what they do, but
-do not invoke them yourself.
-
-## How to identify "is this an OpenKB knowledge base?"
+- `openkb init` — one-time KB setup
+- `openkb use <path>` — set the default KB
 
-Look for a `.openkb/` directory alongside `wiki/` in the user's cwd
-(or an ancestor). The presence of `.openkb/config.yaml` confirms it.
-If the user's question is about content but no KB is present, suggest
-they `openkb init` and `openkb add` their documents.
+Also: never directly `Edit`/`Write` any file under `<kb>/wiki/` or
+`<kb>/.openkb/`. That's the user's curated content (and openkb's
+internal state) — the agent must not patch it directly.