@vercora-protocol/sdk 0.0.13 → 0.0.15

package/README.md

@@ -47,6 +47,7 @@ Most transaction methods use **`provider.wallet.publicKey`** as the signer (`use
 | `types`                  | Params and account shapes (`CreateMarketParams`, `ListedMarket`, …).                         |
 | `marketUi`               | Pure UI helpers (`getMarketLifecycleStatus`, `formatTimeLeft`, …).                           |
 | `Vercora` (type)         | Anchor `Program` generic for `Program<Vercora>`.                                             |
+| `agents/skill.md`        | Short **AI agent entrypoint** (production: `https://vercora.xyz/agents/skill.md`). |
 
 ---
 
@@ -495,6 +496,8 @@ import type {
 
 ## AI agent integration
 
+Start from **`agents/skill.md`** in this package for a stable entrypoint; the full playbook is at **`https://vercora.xyz/agents/playbook.md`** (production), or `docs/AI-AGENT-SDK-PLAYBOOK.md` in the monorepo.
+
 1. **Bootstrap**: `Connection` → `AnchorProvider` → `Program<Vercora>` from `IDL` → `PredictionMarketClient`.
 2. **Branch**: `fetchMarket` → `market.marketType` (`completeSet` vs `parimutuel`).
 3. **Flows**:

package/agents/skill.md

@@ -0,0 +1,72 @@
+# Vercora Protocol — agent skill entry (`@vercora-protocol/sdk`)
+
+This file ships **inside** the npm package (`agents/skill.md`) so AI agents, clawbots, and operator scripts can load instructions without depending on a particular website.
+
+## Public production deployment (Vercora)
+
+The canonical HTTPS deployment—use this when you **do not** have the monorepo—is **[vercora.xyz](https://vercora.xyz)**. Fetch these over TLS; use a Solana `Connection` and cluster that match the deployment you operate against (see this package’s `README.md`).
+
+| Resource | URL |
+|----------|-----|
+| Full AI playbook (markdown) | `https://vercora.xyz/agents/playbook.md` |
+| This skill entry (markdown) | `https://vercora.xyz/agents/skill.md` |
+| Pointer manifest (JSON) | `https://vercora.xyz/.well-known/vercora-agents.json` |
+| Developer docs (human) | `https://vercora.xyz/docs` |
+| AI / agents page (human) | `https://vercora.xyz/docs/agents` |
+
+Example:
+
+```http
+GET https://vercora.xyz/agents/playbook.md
+```
+
+## Other front-end deployments
+
+For self-hosted or staging sites, use the same path suffixes with your origin: `{BASE}/agents/playbook.md`, `{BASE}/agents/skill.md`, `{BASE}/.well-known/vercora-agents.json` (where `BASE` is `https://your-host` with no trailing slash).
+
+## What to read first
+
+1. **This package’s `README.md`** — install, exports, `PredictionMarketClient` API, and the **AI agent integration** section (workflow map).
+2. **Full playbook** (skills, pitfalls, decision trees):
+   - **Production:** `https://vercora.xyz/agents/playbook.md`
+   - **Monorepo (contributors):** `prediction_market/docs/AI-AGENT-SDK-PLAYBOOK.md` (content matches the production mirror).
+
+The playbook is the source of truth for instruction order, branching, and edge cases.
+
+## Key files in the published npm package
+
+Paths are under `node_modules/@vercora-protocol/sdk/` after install.
+
+| Path | Purpose |
+|------|---------|
+| `README.md` | Install, API tables, examples, AI agent integration |
+| `agents/skill.md` | This entry |
+| `dist/index.js` / `dist/index.d.ts` | Package entry (`PredictionMarketClient`, re-exports) |
+| `dist/idl/vercora.json` | Anchor **IDL** JSON (`IDL` / `PROGRAM_ID` match this release) |
+| `dist/client.js` | `PredictionMarketClient` implementation |
+| `dist/types.d.ts` | `CreateMarketParams`, `MarketAccount`, `UpdateParimutuelStateParams`, etc. |
+| `dist/generated/vercora.d.ts` | Anchor codegen types; use as `Program<Vercora>` generic |
+| `dist/pda.d.ts` | PDA helpers (`deriveMarket`, `deriveVault`, …) |
+| `dist/marketUi.d.ts` | `getMarketLifecycleStatus`, `formatTimeLeft`, … |
+| `package.json` | Version and peer dependencies |
+
+## Monorepo paths (source / docs, not shipped in npm)
+
+| Path | Purpose |
+|------|---------|
+| `prediction_market/docs/AI-AGENT-SDK-PLAYBOOK.md` | Full AI playbook (synced to `https://vercora.xyz/agents/playbook.md`) |
+| `prediction_market/docs/market-mechanics-and-ux-options.md` | Mechanics and UX notes (non-normative) |
+| `prediction_market/app/sdk/src/` | SDK TypeScript source |
+| `prediction_market/target/idl/vercora.json` | IDL from `anchor build` (synced into SDK + web) |
+| `prediction_market/programs/vercora/` | On-chain program (Rust) |
+| `prediction_market/app/web/public/.well-known/vercora-agents.json` | Pointer manifest (deployed at `https://vercora.xyz/.well-known/vercora-agents.json`) |
+
+## NPM
+
+- Package: `@vercora-protocol/sdk`
+- See `package.json` for the published version; align Anchor program + IDL with the same release when possible.
+
+## Quick guardrails (parimutuel)
+
+- After `fetchMarket(marketPda)`, read **`isEarlyWithdrawAllowed`**. If `false`, do not propose **`parimutuelWithdraw`** until close/resolution (on-chain error **`EarlyWithdrawNotAllowed`**). Creators may change this with **`updateParimutuelState`** (with penalty bps).
+- Use **`isClosedEarly`**, **`isVoided`**, **`winningOutcomeIndex`** for lifecycle — not legacy `closed` / `voided` / `resolvedOutcomeIndex` names.

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "@vercora-protocol/sdk",
-  "version": "0.0.13",
+  "version": "0.0.15",
   "description": "TypeScript SDK for the Vercora protocol on Solana",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "files": [
     "dist",
-    "README.md"
+    "README.md",
+    "agents"
   ],
   "publishConfig": {
     "access": "public",