@openontology/opencode-palantir 0.1.1 → 0.1.2

package/README.md

@@ -1,14 +1,114 @@
 # opencode-palantir
 
-OpenCode plugin that provides Palantir Foundry documentation to AI agents via local Parquet storage.
+OpenCode plugin that provides **Palantir Foundry documentation** to AI agents via a local Parquet
+database.
 
 ## Features
 
 - Fetches all ~3,600 pages from Palantir's public documentation
-- Stores in local Parquet file for fast offline access (~17MB)
+- Stores in a local Parquet file for fast offline access (~17MB)
 - Exposes `get_doc_page` and `list_all_docs` tools for AI agents
 
-## Setup
+## Quick start (OpenCode users)
+
+### 1) Enable the plugin in `opencode.json` / `opencode.jsonc`
+
+Add the plugin to your OpenCode config:
+
+```jsonc
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugin": ["@openontology/opencode-palantir@^0.1.1"]
+}
+```
+
+Restart OpenCode.
+
+### 2) (Optional) Install per-project
+
+In your project repo, add the plugin as a dependency inside `.opencode/` (keeps plugin deps separate
+from your app deps):
+
+```bash
+mkdir -p .opencode
+
+cat > .opencode/package.json <<'EOF'
+{
+  "dependencies": {
+    "@openontology/opencode-palantir": "^0.1.1"
+  }
+}
+EOF
+
+(cd .opencode && bun install)
+```
+
+Then create a tiny wrapper file in `.opencode/plugins/`:
+
+Create a tiny wrapper file in `.opencode/plugins/`:
+
+```bash
+mkdir -p .opencode/plugins
+
+cat > .opencode/plugins/opencode-palantir.js <<'EOF'
+import plugin from '@openontology/opencode-palantir';
+
+export default plugin;
+EOF
+```
+
+OpenCode automatically loads `.js`/`.ts` files from `.opencode/plugins/` at startup.
+
+> If your OpenCode setup uses an `opencode.json` / `opencode.jsonc` that restricts plugin loading,
+> make sure `.opencode/plugins/` (or the specific plugin file) is included.
+
+### 3) Get `docs.parquet`
+
+This package does **not** ship with docs bundled. You have two options:
+
+#### Option A (recommended): fetch inside OpenCode
+
+In OpenCode, run:
+
+- `/refresh-docs`
+
+This downloads the docs and writes them to `data/docs.parquet` in your project root.
+
+#### Option B: download a prebuilt Parquet file
+
+Download `data/docs.parquet` from this GitHub repo and place it at:
+
+- `<your-project>/data/docs.parquet`
+
+## Using the tools
+
+When installed, this plugin exposes:
+
+- **`get_doc_page`** - Retrieve a specific doc page by URL
+- **`list_all_docs`** - List all available documentation pages
+
+If `data/docs.parquet` is missing, both tools will instruct you to run `/refresh-docs`.
+
+## Foundry MCP setup helpers
+
+This plugin also provides two OpenCode commands to set up `palantir-mcp` with project-scoped tool
+gating and Foundry sub-agents:
+
+- **`/setup-palantir-mcp <foundry_api_url>`**
+  - Creates/patches repo-root `opencode.jsonc`
+  - Adds `mcp.palantir-mcp` (if missing) as a local `npx palantir-mcp --foundry-api-url ...` server
+  - Enforces global deny: `tools.palantir-mcp_* = false`
+  - Creates `foundry-librarian` and `foundry` agents
+  - Dynamically discovers the current `palantir-mcp` tool list and writes explicit `true/false`
+    per-tool toggles under each Foundry agent
+- **`/rescan-palantir-mcp-tools`**
+  - Re-discovers the `palantir-mcp` tool list and adds any missing explicit toggles
+  - Never overwrites existing `palantir-mcp_*` toggles
+
+Auth is always env-only. The token is referenced as `{env:FOUNDRY_TOKEN}` and is never written to
+disk.
+
+## Setup (this repo)
 
 ```bash
 bun install
@@ -73,15 +173,13 @@ When installed as an OpenCode plugin, exposes:
 - **`list_all_docs`** - List all available documentation pages
 - **`/refresh-docs`** - Command hook to re-fetch all documentation
 
-### Installing in OpenCode (this project only)
+### Installing in OpenCode (this repo only)
 
-Create a tiny wrapper plugin file that re-exports the built artifact into the project-level auto-discovered plugins directory:
+For local development against `dist/`, you can point the wrapper at the built artifact:
 
 ```bash
 mkdir -p .opencode/plugins
-```
 
-```bash
 cat > .opencode/plugins/opencode-palantir.js <<'EOF'
 import plugin from '../../dist/index.js';
 
@@ -89,8 +187,6 @@ export default plugin;
 EOF
 ```
 
-OpenCode automatically loads any `.js`/`.ts` files in `.opencode/plugins/` at startup.
-
 ## Development
 
 Build the plugin:
@@ -123,6 +219,10 @@ Format with Prettier:
 mise run format
 ```
 
+## Release notes
+
+For maintainers, see `RELEASING.md`.
+
 ## Author
 
 Anand Pant <anand@shpit.dev>