@cubocompany/opengem 0.1.0 → 0.2.1

package/README.md

@@ -1,136 +1,136 @@
-# Obsidian OpenCode Plugin
+# OpenGem
 
-OpenCode plugin that bundles Obsidian skills metadata and exposes MVP Obsidian CLI-backed tools.
+> OpenCode plugin for Obsidian — turn your vault into a compounding knowledge base powered by AI.
+
+OpenGem connects [OpenCode](https://opencode.ai) to your [Obsidian](https://obsidian.md) vault via the official Obsidian CLI. You can read and write notes, build a structured wiki, ingest articles, query with citations, and more — all from natural language inside OpenCode.
 
 ## Requirements
 
-- [OpenCode](https://opencode.ai) installed
-- [Obsidian](https://obsidian.md) desktop app running
-- [obsidian CLI](https://github.com/obsidianmd/obsidian-cli) installed and on PATH
+- [OpenCode](https://opencode.ai) installed and on PATH
+- [Obsidian](https://obsidian.md) desktop app installed and running
+- [Obsidian CLI](https://obsidian.md/cli) installed and on PATH (`obsidian --version` should work)
 
 ## Install
 
-### From npm (recommended)
-
-Add the plugin to your `opencode.json`:
-
-```json
-{
-  "plugin": ["obsidian-opencode-plugin"]
-}
-```
-
-### Local development
-
-Clone the repository and link it via `.opencode/plugins/`:
-
 ```bash
-git clone https://github.com/your-org/obsidian-opencode-plugin
-cd obsidian-opencode-plugin
-bun install
+npx @cubocompany/opengem init
 ```
 
-Then add to your `opencode.json`:
+The setup wizard will:
+- Check that the Obsidian CLI and app are available
+- Let you pick your vault
+- Write the config to `~/.opencode/opencode.json` (or your project folder)
+- Initialize the wiki folder structure inside your vault
 
-```json
-{
-  "plugin": ["/absolute/path/to/obsidian-opencode-plugin/src/index.ts"]
-}
-```
+That's it — no JSON editing required.
 
-## Configuration
+## Wiki structure
 
-Pass options in `opencode.json`:
+`opengem init` creates the following inside your vault:
 
-```json
-{
-  "plugin": [
-    ["obsidian-opencode-plugin", {
-      "defaultVault": "My Vault"
-    }]
-  ]
-}
+```
+wiki/
+  INDEX.md       ← auto-generated index of all wiki pages
+  LOG.md         ← append-only log of every ingest and query
+schema/
+  SCHEMA.md      ← conventions for wiki pages (edit to customize)
+raw/
+  .keep          ← original sources go here, untouched
 ```
 
-| Option | Type | Default | Description |
-|---|---|---|---|
-| `defaultVault` | `string` | `null` | Default vault for write operations |
-
-## Skills
+Safe to re-run — existing files are skipped unless you pass `force: true` inside OpenCode.
 
-The plugin vendors five Obsidian skills into `~/.opencode/skills/obsidian-opencode-plugin-bundled/` (bundled mode) or reads from an existing checkout.
+## Usage
 
-To sync bundled skills from upstream:
+Once initialized, just talk to OpenCode naturally:
 
-```bash
-bun run sync:skills
-```
-
-To sync from a local checkout:
-
-```bash
-bun run sync:skills --source=/path/to/obsidian-skills
-```
+| What you say | What happens |
+|---|---|
+| "Add this article to my wiki: https://..." | Fetches, ingests to `raw/` and `wiki/` |
+| "What do I know about X?" | Searches wiki, answers with citations, saves to `wiki/answers/` |
+| "Update my wiki page on Y" | Rewrites the page with new information |
+| "Check my wiki for issues" | Runs lint — broken links, missing metadata |
+| "Refresh my wiki index" | Rebuilds `wiki/INDEX.md` |
 
-## Tools
+## Configuration
 
-| Tool | Description | Requires CLI | Requires App |
+| Option | Type | Default | Description |
 |---|---|---|---|
-| `obsidian_env_doctor` | Environment diagnostics | no* | no |
-| `obsidian_skills_check` | Validate discoverable skills | no | no |
-| `obsidian_read` | Read a note by name or path | yes | yes |
-| `obsidian_search` | Search vault content | yes | yes |
-| `obsidian_create_note` | Create a new note | yes | yes |
-| `obsidian_append_note` | Append text to a note | yes | yes |
-| `obsidian_set_property` | Set a frontmatter property | yes | yes |
+| `defaultVault` | `string` | auto-detected | Target vault for all operations |
 
-\* `obsidian_env_doctor` checks whether the CLI is available but does not require it to run.
+Vault resolution order:
+1. Explicit `vault` arg on the tool call
+2. `defaultVault` in config
+3. Active vault detected via `obsidian vault`
+4. If only one vault exists, uses it automatically
 
-### Vault resolution
+## Tools
 
-- **Read operations** (`read`, `search`): explicit `vault` arg → `defaultVault` config → active app vault
-- **Write operations** (`create`, `append`, `set_property`): explicit `vault` arg → `defaultVault` config → error
+### Wiki workflows
+| Tool | Description |
+|---|---|
+| `obsidian_wiki_init` | Set up wiki folder structure (run once) |
+| `obsidian_wiki_ingest` | Save a source to `raw/` and create a `wiki/` page |
+| `obsidian_wiki_update` | Rewrite a wiki page with new content |
+| `obsidian_wiki_search_cited` | Search wiki and return results with citations |
+| `obsidian_wiki_save_answer` | Save an answer to `wiki/answers/` |
+| `obsidian_wiki_refresh_index` | Regenerate `wiki/INDEX.md` |
+| `obsidian_wiki_lint` | Check for broken links and missing metadata |
+
+### Vault operations
+| Tool | Description |
+|---|---|
+| `obsidian_read` | Read a note by name or path |
+| `obsidian_search` | Search vault content |
+| `obsidian_create_note` | Create a new note |
+| `obsidian_append_note` | Append text to a note |
+| `obsidian_set_property` | Set a frontmatter property |
+| `obsidian_backlinks` | List backlinks to a note |
+| `obsidian_tags` | List all tags in the vault |
+| `obsidian_tag_notes` | List notes with a specific tag |
+
+### Developer tools
+| Tool | Description |
+|---|---|
+| `obsidian_eval` | Execute JavaScript in Obsidian |
+| `obsidian_dev_errors` | Show captured errors |
+| `obsidian_dev_console` | Show captured console messages |
+| `obsidian_dev_screenshot` | Take a screenshot |
+| `obsidian_dev_dom` | Query DOM elements |
+| `obsidian_dev_css` | Inspect CSS |
+| `obsidian_plugins` | List installed plugins |
+| `obsidian_plugin_reload` | Reload a plugin |
+
+### Diagnostics
+| Tool | Description |
+|---|---|
+| `obsidian_env_doctor` | Check CLI, app, vault, and skills status |
 
-### Degraded mode
+## Manual config (optional)
 
-All tools remain registered when prerequisites are missing. A structured error envelope is returned instead:
+If you prefer to configure manually instead of running `init`, add to your `opencode.json`:
 
 ```json
 {
-  "ok": false,
-  "error": {
-    "code": "CLI_NOT_FOUND",
-    "kind": "capability",
-    "message": "obsidian CLI is not installed or not on PATH"
-  },
-  "hint": "Ask OpenCode to use obsidian_env_doctor"
+  "plugin": [
+    ["@cubocompany/opengem", {
+      "defaultVault": "My Vault"
+    }]
+  ]
 }
 ```
 
-### Error codes
-
-| Code | Cause |
-|---|---|
-| `CLI_NOT_FOUND` | `obsidian` binary not on PATH |
-| `APP_NOT_RUNNING` | Obsidian desktop app not running |
-| `VAULT_REQUIRED` | Write operation with no vault specified |
-| `VAULT_NOT_FOUND` | Specified vault does not exist |
-| `FILE_OR_PATH_REQUIRED` | Neither `file` nor `path` provided |
-| `MUTUALLY_EXCLUSIVE_TARGET` | Both `file` and `path` provided |
-| `PATH_OUTSIDE_VAULT` | Path traversal attempt rejected |
-| `BUNDLED_SKILLS_OUT_OF_SYNC` | Skills missing from expected path |
-
 ## Development
 
 ```bash
-bun install          # install dependencies
-bun test             # run all tests
-bun run check        # TypeScript type-check
-bun run sync:skills  # sync skills from upstream GitHub
+git clone https://github.com/cubocompany/opengem
+cd opengem
+bun install
+bun test          # 121 tests
+bun run check     # TypeScript type-check
+bun run build     # builds dist/index.js (plugin) and dist/cli.js (init CLI)
 ```
 
-## Roadmap
+## License
 
-- **v1** (current): runtime compatibility — env doctor, skills check, read, search, create, append, set-property
-- **v1.5**: vault helpers, wikilink/frontmatter validation, backlinks, tags, dev tooling
-- **v2**: LLM Wiki workflows — source ingestion, page updates, index refresh, answer-with-citations
+MIT