docs: improve end-user README and add releasing guide

Author: anand-testcompare

README.md

@@ -1,14 +1,82 @@
 # 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) Install the plugin
+
+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)
+```
+
+### 2) Load it as an OpenCode plugin
+
+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`.
+
+## Setup (this repo)
 
 ```bash
 bun install
@@ -73,24 +141,20 @@ 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';
 
 export default plugin;
 EOF
 ```
 
-OpenCode automatically loads any `.js`/`.ts` files in `.opencode/plugins/` at startup.
-
 ## Development
 
 Build the plugin:
@@ -123,6 +187,10 @@ Format with Prettier:
 mise run format
 ```
 
+## Release notes
+
+For maintainers, see `RELEASING.md`.
+
 ## Author
 
 Anand Pant <anand@shpit.dev>

RELEASE.md

@@ -19,6 +19,9 @@ We follow [Conventional Commits](https://www.conventionalcommits.org/) specifica
 
 While version is `0.x.x`, breaking changes bump **minor** version.
 
+This repo also intentionally keeps non-breaking `feat:` commits on the same stable line while major
+is `0` (e.g. `0.1.x`).
+
 ### Release Process
 
 1. Push commits to `main` branch
@@ -155,23 +158,12 @@ When you merge a release PR, the GitHub Actions workflow will automatically:
 
 ### Manual Releases
 
-You can also manually trigger a release by pushing a tag in the format `v{semver}`:
-
-```bash
-git tag v1.2.3
-git push origin v1.2.3
-```
-
-This will:
-
-1. Trigger the release workflow
-2. Build and publish to NPM using trusted publishing
-3. Create a GitHub release
+You can manually trigger a publish via GitHub Actions:
 
-Use manual releases for:
+- Run the `Publish Package` workflow with `tag=next` (prerelease)
+- Run the `Publish Package` workflow with `tag=latest` (stable)
 
-- Hot-fixes outside the normal release cycle
-- Bypassing Release Please when needed
-- Direct version control over releases
+Avoid publishing `latest` manually unless you also intend to cut a matching git tag and GitHub
+Release.
 
 **Learn more:** See the [NPM Trusted Publishing documentation](https://docs.npmjs.com/trusted-publishers) for complete setup and best practices.

RELEASING.md

@@ -0,0 +1,56 @@
+# Releasing
+
+This repo publishes the OpenCode plugin package to npm:
+
+- Package: `@openontology/opencode-palantir`
+- Registry: npmjs.com
+
+Releases are automated via **Release Please** + **GitHub Actions** + **npm Trusted Publishing (OIDC)**.
+
+## Release channels
+
+### Stable (`latest`)
+
+Stable releases are created by merging the Release Please PR (example: `chore(main): release 0.1.1`).
+
+What happens after merge:
+
+1. The `Release` workflow runs on `main`
+2. Release Please creates a git tag (e.g. `v0.1.1`) and a GitHub Release
+3. The workflow dispatches `Publish Package` with `tag=latest`
+4. `Publish Package` publishes to npm using OIDC (no npm token)
+
+### Prerelease (`next`)
+
+While a Release Please PR is open, the `Release` workflow dispatches `Publish Package` with `tag=next`.
+
+The prerelease version is computed in `.mise/tasks/publish`:
+
+- Base version = the version currently in `package.json` (e.g. `0.1.0`)
+- Published version = `<base>-next.<N>`
+- `<N>` is the number of commits since the most recent git tag
+
+This is why `next` versions jump frequently and why they reset after a new tag is created.
+
+## How versions are chosen (0.1.x line)
+
+Release Please uses Conventional Commits.
+
+We intentionally stay on a `0.1.x` stable line until we decide to go `1.0.0`.
+The current policy (see `release-please-config.json`) is:
+
+- `fix:` -> patch bump (`0.1.0` -> `0.1.1`)
+- `feat:` -> patch bump while major is `0` (keeps the stable line in `0.1.x`)
+- `feat!:` / `fix!:` / `BREAKING CHANGE:` -> minor bump (`0.1.x` -> `0.2.0`)
+
+If you need a specific version, add a `Release-As: X.Y.Z` footer to a commit on `main`.
+
+## Manual publishing (rare)
+
+The easiest safe manual publish is to run the GitHub workflow:
+
+- Prerelease: `Publish Package` -> input `tag=next`
+- Stable: `Publish Package` -> input `tag=latest`
+
+Avoid publishing `latest` manually unless you also intend to cut a matching git tag and GitHub Release.
+