feat(status): show KB path so agents can locate the wiki from anywhere

The skill in skills/openkb/ implicitly assumed cwd == KB root, but
openkb's own resolution (`_find_kb_dir`) walks up from cwd and falls
back to the global default set by `openkb use` — so a user running
Claude Code from their home directory still has an "active" KB, but
neither the agent nor the user has any obvious way to discover where
it lives. The first smoke test of the skill exposed this: Claude in
the source repo correctly ran `openkb list` first but had no way to
find the wiki.

Fix is one line in `print_status` plus a documentation update —
status now leads with:

    Knowledge base: /absolute/path/to/kb

Agents parse this from the first line; humans see it as natural
context. No new command, no breaking change to existing fields.

Updates the openkb skill (SKILL.md + references/commands.md) to make
`openkb status` the mandatory first step, with the captured path used
for every subsequent Read / Grep / jq call.

Author: KylinMountain

openkb/cli.py

@@ -1019,6 +1019,10 @@ def print_status(kb_dir: Path) -> None:
     wiki_dir = kb_dir / "wiki"
     subdirs = ["sources", "summaries", "concepts", "reports"]
 
+    # Print the active KB path as the first line. Agents and scripts
+    # parse this to locate the wiki without assuming cwd == KB root.
+    click.echo(f"Knowledge base: {kb_dir}")
+    click.echo("")
     click.echo("Knowledge Base Status:")
     click.echo(f"  {'Directory':<20} {'Files':<10}")
     click.echo(f"  {'-'*20} {'-'*10}")
@@ -1068,7 +1072,11 @@ def print_status(kb_dir: Path) -> None:
 @cli.command()
 @click.pass_context
 def status(ctx):
-    """Show the current status of the knowledge base."""
+    """Show the current status of the knowledge base.
+
+    Output starts with a ``Knowledge base: <path>`` line so agents and
+    scripts can locate the wiki without assuming cwd == KB root.
+    """
     kb_dir = _find_kb_dir(ctx.obj.get("kb_dir_override"))
     if kb_dir is None:
         click.echo("No knowledge base found. Run `openkb init` first.")

skills/openkb/SKILL.md

@@ -24,32 +24,62 @@ The wiki holds three kinds of pages:
 - **Source files** at `wiki/sources/*.{md,json}` — full text for short
   docs (`.md`) or a paginated content array for long PDFs (`.json`).
 
+## First: find where the KB lives
+
+The user may invoke you from anywhere — the active knowledge base is
+not necessarily in your current working directory. Run `openkb status`
+to discover the KB root and a summary in one call:
+
+```
+$ openkb status
+Knowledge base: /Users/.../my-kb
+
+Knowledge Base Status:
+  Directory            Files
+  -------------------- ----------
+  sources              5
+  summaries            5
+  concepts             12
+  ...
+```
+
+The first line — `Knowledge base: <path>` — is the absolute path you
+should use for every `Read` / `Grep` / `jq` call below. The same
+resolution rules `openkb` itself uses apply: walks up from cwd looking
+for `.openkb/`, then falls back to the global default set by
+`openkb use`.
+
+If `openkb status` says "No knowledge base found", tell the user to
+`cd` into their KB or run `openkb init` to create one — don't proceed.
+
 ## See what's available
 
-Use any of these to discover the catalog before drilling in:
+After capturing the KB path from `openkb status`, drill in via:
 
 - `openkb list` — table of ingested documents (name, type, page count)
   plus the concept list.
-- `openkb status` — overall stats (doc count, concept count).
-- `Read wiki/index.md` — the compiled table of contents. Every
+- `Read <kb>/wiki/index.md` — the compiled table of contents. Every
   document and concept has a one-line `brief`. Scan this and pick the
   slugs that semantically match the user's question.
 
 ## Read content
 
+(Paths shown relative to the KB root from `openkb where`. Prepend it
+in real calls.)
+
 | Goal | How |
 |---|---|
-| Read a concept page | `Read wiki/concepts/<slug>.md` |
-| Read a document's summary | `Read wiki/summaries/<doc>.md` |
-| Read a short doc's full text | `Read wiki/sources/<doc>.md` |
-| Read a long doc's specific page | `jq '.[N]' wiki/sources/<doc>.json` (page N, 0-indexed) |
+| Read a concept page | `Read <kb>/wiki/concepts/<slug>.md` |
+| Read a document's summary | `Read <kb>/wiki/summaries/<doc>.md` |
+| Read a short doc's full text | `Read <kb>/wiki/sources/<doc>.md` |
+| Read a long doc's specific page | `jq '.[N]' <kb>/wiki/sources/<doc>.json` (page N, 0-indexed) |
 | Get a synthesized answer across sources | `openkb query "<question>"` |
-| Find an exact phrase | `Grep -r "<phrase>" wiki/` |
-| Follow a `[[wikilink]]` | `Read` the linked path |
+| Find an exact phrase | `Grep -r "<phrase>" <kb>/wiki/` |
+| Follow a `[[wikilink]]` | `Read` the linked path under `<kb>/wiki/` |
 
 Concept and summary bodies use `[[concepts/<slug>]]` and
-`[[summaries/<doc>]]` wikilinks. They are relative paths — follow them
-by Reading the corresponding file.
+`[[summaries/<doc>]]` wikilinks. They are wiki-relative paths — follow
+them by Reading `<kb>/wiki/<target>.md`.
 
 ## Frontmatter
 

skills/openkb/references/commands.md

@@ -37,18 +37,35 @@ Concepts (5):
 
 ## `openkb status`
 
-Knowledge base overview (run from inside a KB directory).
+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.
 
 ```
 $ openkb status
-Knowledge base at /path/to/kb
-  Documents:   2  (long_pdf: 1, short: 1)
-  Concepts:    5
-  Last ingest: 2026-05-16 12:14:12  (paper.pdf)
+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
 ```
 
-Use this as a first read when the user asks "what does your KB look
-like?" or "how big is the KB?".
+- 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.
 
 ## `openkb query "<question>"`
 

tests/test_list_status.py

@@ -148,3 +148,22 @@ def test_status_exit_code_zero(self, tmp_path):
             result = runner.invoke(cli, ["status"])
 
         assert result.exit_code == 0
+
+
+class TestStatusKbPath:
+    """Status output must lead with the active KB path so agents and
+    scripts can locate the wiki when invoked from outside the KB root."""
+
+    def test_status_prints_kb_path_first(self, tmp_path):
+        kb_dir = _setup_kb(tmp_path)
+
+        runner = CliRunner()
+        with patch("openkb.cli._find_kb_dir", return_value=kb_dir):
+            result = runner.invoke(cli, ["status"])
+
+        assert result.exit_code == 0
+        # First non-empty line carries the path in a parseable form:
+        #   "Knowledge base: /path/to/kb"
+        first_line = result.output.splitlines()[0]
+        assert first_line.startswith("Knowledge base: ")
+        assert first_line.split(": ", 1)[1] == str(kb_dir)