@openviking/opencode-plugin 0.1.5

package/INSTALL-ZH.md

@@ -0,0 +1,225 @@
+# 安装 OpenViking OpenCode 统一插件
+
+这个插件新增了一个面向 OpenCode 的统一 OpenViking 插件：
+
+- 外部仓库语义检索
+- 长期记忆、session 同步、生命周期边界 commit、自动 recall
+
+这是仓库中唯一继续维护的 OpenCode 插件示例。这个插件不再安装 `skills/openviking/SKILL.md`，也不要求 agent 使用 `ov` 命令。原 skill 风格的能力会通过 OpenCode tools 暴露。
+
+## 前置条件
+
+需要先准备：
+
+- OpenCode
+- OpenViking HTTP Server
+- Node.js / npm，用于安装插件依赖
+- 如果服务端启用了认证，需要可用的 OpenViking API Key
+
+建议先启动 OpenViking：
+
+```bash
+openviking-server --config ~/.openviking/ov.conf
+```
+
+检查服务：
+
+```bash
+curl http://localhost:1933/health
+```
+
+## 安装方式一：发布包安装
+
+普通用户推荐通过 OpenCode 的 package plugin 机制启用：
+
+```json
+{
+  "plugin": ["@openviking/opencode-plugin"]
+}
+```
+
+## 安装方式二：源码安装
+
+用于开发调试或 PR 测试。OpenCode 推荐插件目录：
+
+```bash
+~/.config/opencode/plugins
+```
+
+在仓库根目录执行：
+
+```bash
+mkdir -p ~/.config/opencode/plugins/openviking
+cp examples/opencode-plugin/wrappers/openviking.js ~/.config/opencode/plugins/openviking.js
+cp examples/opencode-plugin/index.mjs examples/opencode-plugin/package.json ~/.config/opencode/plugins/openviking/
+cp -r examples/opencode-plugin/lib ~/.config/opencode/plugins/openviking/
+cd ~/.config/opencode/plugins/openviking
+npm install
+```
+
+安装后结构应类似：
+
+```text
+~/.config/opencode/plugins/
+├── openviking.js
+└── openviking/
+    ├── index.mjs
+    ├── package.json
+    ├── lib/
+    └── node_modules/
+```
+
+顶层 `openviking.js` 只负责把 OpenCode 能发现的一级 `.js` 入口转发到插件目录：
+
+```js
+export { OpenVikingPlugin, default } from "./openviking/index.mjs"
+```
+
+这个 wrapper 只用于上面这种源码安装目录结构。npm 包安装会通过 `package.json` 直接加载 `index.mjs`。
+源码安装请使用 `.js` wrapper；OpenCode 的本地插件扫描器会发现 JavaScript/TypeScript 插件文件。
+
+如果你使用 npm 包方式安装，也可以将 `examples/opencode-plugin` 作为一个普通 OpenCode 插件包使用。
+
+## 配置
+
+创建用户级配置文件：
+
+```bash
+~/.config/opencode/openviking-config.json
+```
+
+示例配置：
+
+```json
+{
+  "endpoint": "http://localhost:1933",
+  "apiKey": "",
+  "account": "",
+  "user": "",
+  "peerId": "",
+  "enabled": true,
+  "timeoutMs": 30000,
+  "repoContext": { "enabled": true, "cacheTtlMs": 60000 },
+  "autoRecall": {
+    "enabled": true,
+    "limit": 6,
+    "scoreThreshold": 0.15,
+    "maxContentChars": 500,
+    "preferAbstract": true,
+    "tokenBudget": 2000
+  }
+}
+```
+
+推荐通过环境变量提供 API Key，而不是写入配置文件：
+
+```bash
+export OPENVIKING_API_KEY="your-api-key-here"
+```
+
+`apiKey` 会作为 `X-API-Key` 发送。`account` 和 `user` 是 trusted mode
+身份头，会作为 `X-OpenViking-Account`、`X-OpenViking-User` 发送；使用
+user/admin API key 的 API_KEY mode 时应留空。
+`peerId` 会作为 `X-OpenViking-Actor-Peer` 用于数据面的 memory/resource 请求；捕获 session message 时仍写入 body `peer_id`。需要 peer 维度路由时请显式配置。
+
+`OPENVIKING_API_KEY`、`OPENVIKING_ACCOUNT`、`OPENVIKING_USER`、
+`OPENVIKING_PEER_ID`
+优先级高于 `openviking-config.json` 里的同名配置。
+
+高级场景可以用 `OPENVIKING_PLUGIN_CONFIG` 指向其他配置文件路径。
+
+## 验证
+
+修改插件或 OpenViking 配置后，需要重启 OpenCode。
+
+进入新的 OpenCode session 后，可以让 agent 浏览 OpenViking memory，或搜索一个已索引的资源。插件应暴露这些 tools：
+
+- `memsearch`、`memread`、`membrowse`
+- `memgrep`、`memglob`
+- `memadd`、`memwrite`、`memremove`、`memqueue`
+- `memcommit`
+- `codesearch`、`codeoutline`、`codeexpand`
+
+如果行为异常，先查看运行时文件：
+
+```bash
+ls ~/.config/opencode/openviking/
+tail -n 100 ~/.config/opencode/openviking/openviking-memory.log
+```
+
+如果使用本地 server，也确认 OpenViking 可访问：
+
+```bash
+curl http://localhost:1933/health
+```
+
+## 可用工具
+
+插件会通过 OpenCode `tool` hook 暴露这些工具：
+
+- `memsearch`：语义检索 memories/resources/skills
+- `memread`：读取具体 `viking://` URI
+- `membrowse`：浏览 OpenViking 文件系统
+- `memcommit`：提交当前 session 并触发记忆提取
+- `memgrep`：精确文本或模式搜索，替代原 `ov grep`
+- `memglob`：文件 glob 枚举，替代原 `ov glob`
+- `memadd`：添加远端 URL 或本地文件资源，替代常见 `ov add-resource` 场景
+- `memwrite`：通过 `/api/v1/content/write` 直接写入 `viking://` 文本文件
+- `memremove`：删除资源，替代 `ov rm`
+- `memqueue`：查看处理队列，替代 `ov observer queue`
+
+使用建议：
+
+- 概念性问题用 `memsearch`
+- 精确符号、函数名、类名、报错字符串用 `memgrep`
+- 枚举文件用 `memglob`
+- 读取内容用 `memread`
+- 探索目录结构用 `membrowse`
+- 持久化笔记或小型文本更新用 `memwrite`；默认是 `create`，避免误覆盖
+- 删除前必须先获得用户明确确认，再调用 `memremove` 且传入 `confirm: true`
+- 如果 agent 误用 OpenCode 本地 `read`、`glob`、`grep` 工具访问 `viking://` URI，插件会阻止这次本地文件系统调用，并提示改用 `memread`、`membrowse` 或 `memsearch`。
+
+## `memadd` 本地文件
+
+`memadd` 支持三类输入：
+
+- 远端 `http(s)` URL：直接调用 `/api/v1/resources`
+- 本地文件路径：先调用 `/api/v1/resources/temp_upload`，再用返回的 `temp_file_id` 添加资源
+- `file://` URL：按本地文件处理
+
+相对路径会按 OpenCode 当前项目目录解析。示例：
+
+```text
+memadd path="https://example.com/spec.md" to="viking://resources/spec"
+memadd path="./docs/notes.md" parent="viking://resources/"
+memadd path="file:///home/alice/project/notes.md" reason="project notes"
+```
+
+当前仍不支持本地目录自动打 zip 上传；传入目录时会返回明确错误。
+
+## 运行时文件
+
+插件默认会把运行时文件写入：
+
+```bash
+~/.config/opencode/openviking/
+```
+
+可能包含：
+
+- `openviking-memory.log`
+- `openviking-session-map.json`
+
+可以通过配置里的 `runtime.dataDir` 修改这个目录。
+
+这些是本地运行时文件，不建议提交到版本库。
+
+## 故障排查
+
+| 问题 | 排查方向 |
+|------|----------|
+| 插件没有加载 | package 安装检查 `~/.config/opencode/opencode.json` 是否包含 `@openviking/opencode-plugin`；源码安装检查 `~/.config/opencode/plugins/openviking.js` 是否存在 |
+| Tools 连到了错误的 server | 检查 `~/.config/opencode/openviking-config.json` 里的 `endpoint`，或用 `OPENVIKING_PLUGIN_CONFIG` 指向正确配置文件 |
+| OpenViking 返回 401 / 403 | 检查 `OPENVIKING_API_KEY`；trusted-mode 部署还要检查 `OPENVIKING_ACCOUNT` 和 `OPENVIKING_USER` |
+| recall 为空 | 确认 OpenViking 中已有 memories/resources，并且 `autoRecall.enabled` 为 `true` |
+| 本地 `memadd` 失败 | 传入文件路径而不是目录；目前还不支持自动上传本地目录 |

package/INSTALL.md

@@ -0,0 +1,220 @@
+# Install the Unified OpenViking OpenCode Plugin
+
+This plugin adds one unified OpenViking plugin for OpenCode:
+
+- Semantic retrieval for external repositories
+- Long-term memory, session synchronization, lifecycle commit, and automatic recall
+
+This is the only OpenCode plugin example maintained in this repository. It does not install `skills/openviking/SKILL.md`, and it does not require the agent to use the `ov` command. The former skill-style capabilities are exposed as OpenCode tools here.
+
+## Prerequisites
+
+Prepare the following first:
+
+- OpenCode
+- OpenViking HTTP Server
+- Node.js / npm, used to install plugin dependencies
+- A valid OpenViking API key if authentication is enabled on the server
+
+Start OpenViking first:
+
+```bash
+openviking-server --config ~/.openviking/ov.conf
+```
+
+Check the service:
+
+```bash
+curl http://localhost:1933/health
+```
+
+## Installation Method 1: Published Package
+
+Normal users are recommended to enable it through OpenCode's package plugin mechanism:
+
+```json
+{
+  "plugin": ["@openviking/opencode-plugin"]
+}
+```
+
+## Installation Method 2: Source Install
+
+Use this method for development, debugging, or PR testing. OpenCode's recommended plugin directory is:
+
+```bash
+~/.config/opencode/plugins
+```
+
+Run the following commands from the repository root:
+
+```bash
+mkdir -p ~/.config/opencode/plugins/openviking
+cp examples/opencode-plugin/wrappers/openviking.js ~/.config/opencode/plugins/openviking.js
+cp examples/opencode-plugin/index.mjs examples/opencode-plugin/package.json ~/.config/opencode/plugins/openviking/
+cp -r examples/opencode-plugin/lib ~/.config/opencode/plugins/openviking/
+cd ~/.config/opencode/plugins/openviking
+npm install
+```
+
+After installation, the layout should look like this:
+
+```text
+~/.config/opencode/plugins/
+├── openviking.js
+└── openviking/
+    ├── index.mjs
+    ├── package.json
+    ├── lib/
+    └── node_modules/
+```
+
+The top-level `openviking.js` forwards the first-level `.js` entry that OpenCode can discover to the actual plugin directory:
+
+```js
+export { OpenVikingPlugin, default } from "./openviking/index.mjs"
+```
+
+This wrapper is only for source installs with the directory layout shown above. npm package installs load `index.mjs` directly through `package.json`.
+Use the `.js` wrapper for source installs; OpenCode's local plugin scanner discovers JavaScript/TypeScript plugin files.
+
+If you install through an npm package, you can also use `examples/opencode-plugin` as a normal OpenCode plugin package.
+
+## Configuration
+
+Create the user-level configuration file:
+
+```bash
+~/.config/opencode/openviking-config.json
+```
+
+Example configuration:
+
+```json
+{
+  "endpoint": "http://localhost:1933",
+  "apiKey": "",
+  "account": "",
+  "user": "",
+  "peerId": "",
+  "enabled": true,
+  "timeoutMs": 30000,
+  "repoContext": { "enabled": true, "cacheTtlMs": 60000 },
+  "autoRecall": {
+    "enabled": true,
+    "limit": 6,
+    "scoreThreshold": 0.15,
+    "maxContentChars": 500,
+    "preferAbstract": true,
+    "tokenBudget": 2000
+  }
+}
+```
+
+It is recommended to provide the API key through an environment variable instead of writing it into the configuration file:
+
+```bash
+export OPENVIKING_API_KEY="your-api-key-here"
+```
+
+`apiKey` is sent as `X-API-Key`. `account` and `user` are trusted-mode identity headers sent as `X-OpenViking-Account` and `X-OpenViking-User`; leave them empty when using API-key mode with user/admin API keys. `peerId` is sent as `X-OpenViking-Actor-Peer` on data-plane memory/resource requests; captured session messages store it as body `peer_id`.
+
+`OPENVIKING_API_KEY`, `OPENVIKING_ACCOUNT`, `OPENVIKING_USER`, and `OPENVIKING_PEER_ID` take precedence over the corresponding values in `openviking-config.json`.
+
+For advanced setups, use `OPENVIKING_PLUGIN_CONFIG` to point to another configuration file path.
+
+## Verify
+
+Restart OpenCode after changing plugin or OpenViking configuration.
+
+In a new OpenCode session, ask the agent to browse OpenViking memory or search for a known indexed resource. The plugin should expose these tools:
+
+- `memsearch`, `memread`, `membrowse`
+- `memgrep`, `memglob`
+- `memadd`, `memwrite`, `memremove`, `memqueue`
+- `memcommit`
+- `codesearch`, `codeoutline`, `codeexpand`
+
+If anything looks wrong, check the runtime files:
+
+```bash
+ls ~/.config/opencode/openviking/
+tail -n 100 ~/.config/opencode/openviking/openviking-memory.log
+```
+
+For a local server, also confirm OpenViking is reachable:
+
+```bash
+curl http://localhost:1933/health
+```
+
+## Available Tools
+
+The plugin exposes the following tools through the OpenCode `tool` hook:
+
+- `memsearch`: semantic retrieval across memories, resources, and skills
+- `memread`: read a specific `viking://` URI
+- `membrowse`: browse the OpenViking filesystem
+- `memcommit`: commit the current session and trigger memory extraction
+- `memgrep`: exact text or pattern search, replacing the former `ov grep` use case
+- `memglob`: file glob enumeration, replacing the former `ov glob` use case
+- `memadd`: add a remote URL or local file resource, replacing common `ov add-resource` scenarios
+- `memwrite`: write text to a `viking://` file through `/api/v1/content/write`
+- `memremove`: remove resources, replacing `ov rm`
+- `memqueue`: inspect the processing queue, replacing `ov observer queue`
+
+Usage guidance:
+
+- Use `memsearch` for conceptual questions.
+- Use `memgrep` for exact symbols, function names, class names, or error strings.
+- Use `memglob` to enumerate files.
+- Use `memread` to read content.
+- Use `membrowse` to explore directory structure.
+- Use `memwrite` for durable notes or small direct text updates; default mode is `create`.
+- Before deleting anything, obtain explicit user confirmation first; then call `memremove` with `confirm: true`.
+- If an agent tries to use OpenCode's local `read`, `glob`, or `grep` tools on a `viking://` URI, the plugin blocks that call and points it to `memread`, `membrowse`, or `memsearch`.
+
+## Local Files with `memadd`
+
+`memadd` supports three input types:
+
+- Remote `http(s)` URL: directly calls `/api/v1/resources`
+- Local file path: first calls `/api/v1/resources/temp_upload`, then adds the resource using the returned `temp_file_id`
+- `file://` URL: handled as a local file
+
+Relative paths are resolved against the current OpenCode project directory. Examples:
+
+```text
+memadd path="https://example.com/spec.md" to="viking://resources/spec"
+memadd path="./docs/notes.md" parent="viking://resources/"
+memadd path="file:///home/alice/project/notes.md" reason="project notes"
+```
+
+Automatic zip upload for local directories is not supported yet. Passing a directory will return a clear error.
+
+## Runtime Files
+
+By default, the plugin writes runtime files to:
+
+```bash
+~/.config/opencode/openviking/
+```
+
+Possible files include:
+
+- `openviking-memory.log`
+- `openviking-session-map.json`
+
+You can change this directory with `runtime.dataDir` in the configuration.
+
+These are local runtime files and should not be committed to the repository.
+
+## Troubleshooting
+
+| Issue | What to check |
+|-------|---------------|
+| Plugin does not load | For package installs, confirm `~/.config/opencode/opencode.json` contains `@openviking/opencode-plugin`; for source installs, confirm `~/.config/opencode/plugins/openviking.js` exists |
+| Tools call the wrong server | Check `endpoint` in `~/.config/opencode/openviking-config.json`, or set `OPENVIKING_PLUGIN_CONFIG` to the intended config path |
+| 401 / 403 from OpenViking | Verify `OPENVIKING_API_KEY`; for trusted-mode deployments, also verify `OPENVIKING_ACCOUNT` and `OPENVIKING_USER` |
+| Recall is empty | Confirm OpenViking has indexed memories/resources and `autoRecall.enabled` is `true` |
+| Local `memadd` fails | Pass a file path, not a directory; local directories are not uploaded automatically yet |

package/README.md

@@ -0,0 +1,261 @@
+# OpenViking OpenCode Plugin
+
+A unified OpenCode plugin for OpenViking repository retrieval and long-term memory.
+
+This is the only OpenCode plugin example maintained in this repository. It supersedes the former split examples for indexed repository prompt injection and long-term memory.
+
+The new plugin exposes everything through OpenCode tool hooks and talks to OpenViking through HTTP APIs. It does not install or require an OpenCode skill, and agents do not need to run `ov` shell commands.
+
+## What It Does
+
+- Injects indexed `viking://resources/` repositories into the system prompt.
+- Exposes repository search, grep, glob, read, browse, add, write, remove, and queue status as tools.
+- Maps each OpenCode session to an OpenViking session.
+- Captures user and assistant text messages into OpenViking.
+- Commits sessions at lifecycle boundaries for memory extraction.
+- Automatically recalls relevant memories and injects them as hidden synthetic context for the current user message.
+- Blocks accidental local filesystem reads of `viking://` URIs and points the agent back to `memread`, `membrowse`, or `memsearch`.
+
+## Files
+
+```text
+examples/opencode-plugin/
+├── index.mjs
+├── package.json
+├── README.md
+├── INSTALL-ZH.md
+├── lib/
+│   ├── runtime.mjs
+│   ├── repo-context.mjs
+│   ├── memory-session.mjs
+│   ├── memadd-local.mjs
+│   ├── memory-tools.mjs
+│   ├── memory-recall.mjs
+│   ├── viking-uri-guard.mjs
+│   └── utils.mjs
+├── tests/
+└── wrappers/
+    └── openviking.js
+```
+
+There is intentionally no `skills/openviking/SKILL.md`. The former skill behavior is implemented as tools.
+
+## Requirements
+
+- OpenCode
+- OpenViking HTTP server
+- Node.js / npm for installing the plugin dependency
+- An OpenViking API key if your server requires authentication
+
+Start OpenViking first:
+
+```bash
+openviking-server --config ~/.openviking/ov.conf
+```
+
+## Installation
+
+### Published Package
+
+Normal users should enable it through OpenCode's package plugin mechanism:
+
+The published npm package is `@openviking/opencode-plugin`; verify availability with:
+
+```bash
+npm view @openviking/opencode-plugin version
+```
+
+```json
+{
+  "plugin": ["@openviking/opencode-plugin"]
+}
+```
+
+### Source Install
+
+For development or PR testing, copy the package into OpenCode's plugin directory with a top-level wrapper:
+
+```bash
+mkdir -p ~/.config/opencode/plugins/openviking
+cp examples/opencode-plugin/wrappers/openviking.js ~/.config/opencode/plugins/openviking.js
+cp examples/opencode-plugin/index.mjs examples/opencode-plugin/package.json ~/.config/opencode/plugins/openviking/
+cp -r examples/opencode-plugin/lib ~/.config/opencode/plugins/openviking/
+cd ~/.config/opencode/plugins/openviking
+npm install
+```
+
+This creates a stable OpenCode plugin layout:
+
+```text
+~/.config/opencode/plugins/
+├── openviking.js
+└── openviking/
+    ├── index.mjs
+    ├── package.json
+    ├── lib/
+    └── node_modules/
+```
+
+The top-level `openviking.js` is only a wrapper:
+
+```js
+export { OpenVikingPlugin, default } from "./openviking/index.mjs"
+```
+
+This wrapper is only for source installs with the directory layout shown above. npm package installs load `index.mjs` directly through `package.json`.
+Use the `.js` wrapper for source installs; OpenCode's local plugin scanner discovers JavaScript/TypeScript plugin files.
+
+## Configuration
+
+Create `~/.config/opencode/openviking-config.json`:
+
+```json
+{
+  "endpoint": "http://localhost:1933",
+  "apiKey": "",
+  "account": "",
+  "user": "",
+  "peerId": "",
+  "enabled": true,
+  "timeoutMs": 30000,
+  "repoContext": { "enabled": true, "cacheTtlMs": 60000 },
+  "autoRecall": {
+    "enabled": true,
+    "limit": 6,
+    "scoreThreshold": 0.15,
+    "maxContentChars": 500,
+    "preferAbstract": true,
+    "tokenBudget": 2000
+  }
+}
+```
+
+`apiKey` is sent as `X-API-Key`. `account` and `user` are trusted-mode identity
+headers sent as `X-OpenViking-Account` and `X-OpenViking-User`; leave them empty
+when using API-key mode with user/admin API keys.
+`peerId` is sent as `X-OpenViking-Actor-Peer` on data-plane memory/resource
+requests; captured session messages store it as body `peer_id`. Configure
+`peerId` explicitly when peer-scoped memory routing is needed.
+
+`OPENVIKING_API_KEY`, `OPENVIKING_ACCOUNT`, `OPENVIKING_USER`,
+and `OPENVIKING_PEER_ID` take
+precedence over values in this file.
+
+For advanced setups, `OPENVIKING_PLUGIN_CONFIG` can point to another config file path.
+
+OpenCode's local `read`, `glob`, and `grep` tools cannot read `viking://` URIs.
+When the agent accidentally tries that, the plugin blocks the filesystem tool
+call and points it to `memread`, `membrowse`, or `memsearch`.
+
+## Tools
+
+### `memsearch`
+
+Semantic search across memories, resources, and skills.
+
+Use for conceptual questions, repository internals, user preferences, and context-aware retrieval. Use `target_uri` to narrow scope, for example `viking://resources/fastapi/`.
+
+### `memread`
+
+Read a specific `viking://` URI using `abstract`, `overview`, `read`, or `auto`.
+
+Use after `memsearch`, `memgrep`, `memglob`, or `membrowse` returns a URI.
+
+### `membrowse`
+
+Browse OpenViking filesystem structure with `list`, `tree`, or `stat`.
+
+Use to discover exact URIs before reading content.
+
+### `memcommit`
+
+Commit the current OpenCode session to OpenViking and trigger memory extraction.
+
+The plugin also commits at session deletion, session error, compaction, and plugin shutdown boundaries.
+
+### `memgrep`
+
+Pattern search through OpenViking content.
+
+Use for exact symbols, class names, function names, error strings, or known keywords.
+
+### `memglob`
+
+Glob file matching through OpenViking content.
+
+Use to enumerate files such as `**/*.py`, `**/test_*.ts`, or `**/*.md`.
+
+### `memadd`
+
+Add a remote URL or local file resource to OpenViking.
+
+Remote `http(s)` URLs go directly through `POST /api/v1/resources`.
+Local files use the safer two-step server flow: upload the file to
+`POST /api/v1/resources/temp_upload`, then add it through
+`POST /api/v1/resources` with the returned `temp_file_id`.
+
+Local paths may be absolute, relative to the OpenCode project directory, or
+`file://` URLs. Local directory upload is not supported yet.
+
+Examples:
+
+```text
+memadd path="https://example.com/spec.md" to="viking://resources/spec"
+memadd path="./docs/notes.md" parent="viking://resources/"
+memadd path="file:///home/alice/project/notes.md" reason="project notes"
+```
+
+After adding a resource, the tool also returns `GET /api/v1/observer/queue` status.
+
+### `memwrite`
+
+Write text content to a `viking://` file through `POST /api/v1/content/write`.
+
+Use this for durable notes, small project memory files, or resource text that
+should be updated directly. The default mode is `create` to avoid accidental
+overwrites. Use `append` to extend an existing file and `replace` only when the
+user explicitly wants to overwrite the file.
+
+Examples:
+
+```text
+memwrite uri="viking://user/memories/project-notes.md" content="# Decision\n\nUse PostgreSQL." wait=true
+memwrite uri="viking://resources/docs/api.md" content="\n\n## New endpoint" mode="append"
+```
+
+### `memremove`
+
+Remove a `viking://` URI through `DELETE /api/v1/fs`.
+
+This tool requires `confirm: true`. The user must explicitly confirm deletion before the agent calls it.
+
+### `memqueue`
+
+Return OpenViking observer queue status for embedding and semantic processing.
+
+### `codesearch`
+
+Search AST-supported symbol names across a confirmed ingested code repository or source subtree.
+
+Use this after you have evidence that a `viking://` URI contains supported source files.
+
+### `codeoutline`
+
+Show symbol structure for a confirmed `viking://` source file.
+
+Use this after `memglob`, `membrowse`, or `codesearch` finds an exact source file URI.
+
+### `codeexpand`
+
+Return the full source for one named symbol from a confirmed `viking://` source file.
+
+Use this after `codeoutline` or other evidence shows the symbol exists in that file.
+
+## Runtime Files
+
+The plugin writes runtime files to `~/.config/opencode/openviking/` by default:
+
+- `openviking-memory.log`
+- `openviking-session-map.json`
+
+Set `runtime.dataDir` in config to override this directory.