Plugin v2 server companion: OAuth docs, policy pages, marketplace copy

AGENTS.md

@@ -24,3 +24,15 @@ The route tree (`src/routeTree.gen.ts`) is auto-generated by the TanStack Router
 ## Database schema changes
 
 During development, apply schema changes using `bun run db:push` (`drizzle-kit push`) instead of generating migrations. Do **not** run `drizzle-kit generate` or `drizzle-kit migrate` while iterating on schema changes. Migrations should only be generated once, right before submitting the PR.
+
+## Server–plugin synchronization
+
+The plugin lives in the sibling `expert-system-plugin` repository. Do not duplicate it here. This repository owns the MCP server, OAuth, the website, and the public privacy/terms pages.
+
+When changing MCP tool names, arguments, responses, errors, limits, endpoint URLs, OAuth requirements, `public/marketplace.json`, or the policy pages, update the plugin repository in the same change and run its check:
+
+```bash
+bun run plugin:check
+```
+
+Server CI does not run that check. See [documentation/PLUGIN_SYNC.md](documentation/PLUGIN_SYNC.md) for what it covers, what it misses, and release rules.

README.md

@@ -1,6 +1,19 @@
-# STΛR MODΞ 🦨
+# Expert System
 
-Production deployment: https://sworks.starmode.app/
+Backend and website for Expert System research, macroeconomic data, and company financials.
+
+Production: [expert-system.starmode.dev](https://expert-system.starmode.dev).
+
+## Agent plugin
+
+The Claude Code and Codex plugin is maintained and released in
+[expert-system-plugin](https://github.com/starmode-base/expert-system-plugin).
+See that repository for installation, shared skills, manifests, and release checks.
+This repository owns the MCP server, OAuth, website, and public privacy/terms pages.
+
+The hosted `public/marketplace.json` is a compatibility copy of the plugin repo's
+`.claude-plugin/marketplace.json`. When releasing the plugin, update this copy and
+run its cross-repository check with `EXPERT_SYSTEM_SERVER_ROOT` pointing here.
 
 ## Contributing
 

documentation/PLUGIN_SYNC.md

@@ -0,0 +1,30 @@
+# Server–plugin synchronization
+
+Expert System is maintained in two repositories, normally checked out as siblings:
+
+- `expert-system` owns the MCP server, OAuth, tool schemas and response semantics, website, and public privacy/terms pages.
+- `expert-system-plugin` owns the plugin manifests, shared skills, installation documentation, packaging tests, and plugin releases. Do not duplicate the plugin package in the server repository.
+
+## What to update together
+
+When changing MCP tool names, arguments, responses, errors, limits, pagination, units, fiscal-period semantics, endpoint URLs, or OAuth requirements, inspect the corresponding code and instructions in **both** repositories. Update affected plugin skills, `agents/openai.yaml` dependencies, manifests, tests, and documentation together with server changes. The server contract is defined by `src/server/mcp/tools.ts` and its referenced schemas/operations; do not infer it from stale skill text.
+
+The plugin's `.claude-plugin/marketplace.json` is canonical. Keep the server's `public/marketplace.json` identical whenever plugin versions, descriptions, or source references change. Keep identity and version metadata synchronized across the plugin's portable, Claude, and Codex manifests; transport declarations must point to the same MCP endpoint. Policy URLs in plugin metadata must correspond to pages hosted by the server.
+
+## Checking
+
+Run this from either repository, in addition to each repository's relevant checks:
+
+```bash
+bun run plugin:check
+```
+
+This repository's script runs the plugin repository's test suite against this checkout. It assumes the repositories are siblings; set `EXPERT_SYSTEM_PLUGIN_ROOT` if they are not. Run from the plugin repository instead with `EXPERT_SYSTEM_SERVER_ROOT=../expert-system bun run plugin:check` — the cross-repository test is skipped when that variable is unset there, so a standalone green run is not synchronization validation.
+
+The plugin repository's CI runs this check on its own pull requests and nightly. Server pull requests do **not** run it, so drift originating here surfaces on the next nightly run at the earliest — run the check locally when changing the contract.
+
+The check verifies tool names, marketplace parity, and policy files. It does not validate argument/response semantics or live OAuth behavior. Review affected schemas and workflows and run relevant server tests; perform client smoke tests when connection or packaging behavior changes. Update contract assertions only for intentional changes, never merely to make drift checks pass.
+
+## Releasing
+
+Preserve compatibility with already-installed plugin versions where possible. For breaking changes, document the required plugin version and rollout order in `documents/plugin-release.md` in the plugin repository. If work spans both repositories, link the companion PRs and report checks for each. If a companion checkout is unavailable, report the synchronization work and checks still needed; do not claim the change is release-ready.

package.json

@@ -14,6 +14,7 @@
     "format": "prettier --write .",
     "lint": "eslint --max-warnings 0 --fix",
     "test": "vitest",
+    "plugin:check": "root=$PWD; cd \"${EXPERT_SYSTEM_PLUGIN_ROOT:-../expert-system-plugin}\" && EXPERT_SYSTEM_SERVER_ROOT=\"$root\" bun run plugin:check",
     "env:pull": "bunx vercel@latest env pull .env && ./scripts/dev-env.sh",
     "clean": "rm -rf node_modules tsconfig.tsbuildinfo bun.lock .output .vinxi && bun install",
     "db:generate": "drizzle-kit generate",

public/marketplace.json

@@ -1,11 +1,21 @@
 {
-  "name": "Expert System",
+  "name": "expert-system",
+  "owner": {
+    "name": "STAR MODE",
+    "url": "https://github.com/starmode-base"
+  },
   "plugins": [
     {
       "name": "expert-system",
-      "source": "github://starmode-base/expert-system-plugin",
-      "version": "1.0.0",
-      "description": "Research intelligence and macroeconomic data for Claude Code"
+      "source": {
+        "source": "github",
+        "repo": "starmode-base/expert-system-plugin"
+      },
+      "version": "2.0.0",
+      "description": "Curated research, FRED macroeconomic data, and SEC company financials with source provenance."
     }
-  ]
+  ],
+  "metadata": {
+    "description": "Expert System research, macroeconomic data, and financials plugins."
+  }
 }

public/privacy.html

@@ -0,0 +1,145 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <meta name="description" content="Expert System Privacy Policy" />
+    <title>Privacy Policy — Expert System</title>
+    <style>
+      body {
+        font:
+          17px/1.65 system-ui,
+          sans-serif;
+        color: #172033;
+        background: #f8fafc;
+        margin: 0;
+      }
+      main {
+        max-width: 760px;
+        margin: 0 auto;
+        padding: 48px 24px 72px;
+      }
+      h1,
+      h2 {
+        line-height: 1.2;
+      }
+      h1 {
+        font-size: 2.5rem;
+      }
+      h2 {
+        margin-top: 2em;
+        font-size: 1.35rem;
+      }
+      a {
+        color: #1d4ed8;
+      }
+      nav {
+        display: flex;
+        flex-wrap: wrap;
+        gap: 20px;
+      }
+      footer {
+        border-top: 1px solid #cbd5e1;
+        margin-top: 40px;
+        padding-top: 20px;
+      }
+    </style>
+  </head>
+  <body>
+    <main>
+      <nav aria-label="Main">
+        <a href="/">Expert System</a><a href="/privacy.html">Privacy</a
+        ><a href="/terms.html">Terms</a>
+      </nav>
+      <h1>Privacy Policy</h1>
+      <p>Last updated: September 20, 2026</p>
+      <p>
+        This policy describes how STAR MODE handles information when you use
+        Expert System, including its website, REST API, and MCP plugin
+        connections.
+      </p>
+      <h2>Information processed</h2>
+      <ul>
+        <li>
+          <strong>Account information:</strong> authentication identifiers and
+          available email, display name, and nickname; plan tier and
+          subscription status.
+        </li>
+        <li>
+          <strong>Requests:</strong> the search text, company identifiers,
+          document IDs, series IDs, date ranges, and other arguments your client
+          sends to fulfill a request. The MCP integration receives tool
+          arguments, not automatic access to your full chat history or local
+          files.
+        </li>
+        <li>
+          <strong>Usage and technical information:</strong> per-account monthly
+          request counts by endpoint, session and token-revocation records, and
+          operational error logs. Hosting and authentication providers may
+          process connection metadata such as IP addresses and device/browser
+          information.
+        </li>
+        <li>
+          <strong>Billing:</strong> Stripe customer and subscription identifiers
+          and payment status. Payment details are handled through Stripe.
+        </li>
+      </ul>
+      <h2>How information is used</h2>
+      <p>
+        We process information to authenticate users, return requested research
+        and data, enforce access and usage limits, manage subscriptions,
+        troubleshoot failures, and protect the service. Browser sign-in uses
+        cookies and server-side session records. MCP credentials are managed by
+        your client and authentication provider; the distributed plugin contains
+        no user credentials.
+      </p>
+      <h2>Service providers and your AI client</h2>
+      <p>
+        Auth0 handles authentication, Vercel hosts the service, Neon provides
+        database infrastructure, and Stripe handles payments. Research search
+        text is sent to OpenAI to generate embeddings for semantic search.
+        Requests for economic and company data may involve FRED and SEC data
+        services. These providers process information needed for their functions
+        under their applicable terms and privacy practices.
+      </p>
+      <p>
+        Results and, when requested through the profile tool, your available
+        account identifier, name, and email are returned to your connected
+        client. Claude, Codex, and other clients have their own data policies.
+        Information may be processed in countries where we or our providers
+        operate.
+      </p>
+      <h2>Retention and choices</h2>
+      <p>
+        Account, usage, billing, and operational records persist as needed to
+        operate the service and address security, accounting, or legal
+        requirements. There is no single automatic deletion period for all
+        records. Signing out or uninstalling a plugin does not delete your
+        account, cancel a subscription, or remove provider logs and backups.
+      </p>
+      <p>
+        You can stop sending requests, disconnect the plugin, sign out, and
+        manage your subscription from your account. Contact us to request
+        access, correction, or deletion of account information. We may need to
+        verify account ownership; applicable obligations and backup retention
+        may limit immediate deletion. Rights vary by location.
+      </p>
+      <h2>Security and changes</h2>
+      <p>
+        Use the client’s sign-in flow and keep credentials private. No service
+        can guarantee absolute security. We may update this policy as the
+        service changes; the date below identifies this version.
+      </p>
+      <h2>Contact</h2>
+      <p>
+        Contact STAR MODE through
+        <a href="https://github.com/starmode-base/expert-system/issues"
+          >Expert System support</a
+        >. For an account or privacy request, ask for a private contact channel
+        before providing identifying information. Do not post personal data,
+        credentials, or billing details in public issues.
+      </p>
+      <footer>STAR MODE · Expert System</footer>
+    </main>
+  </body>
+</html>

public/terms.html

@@ -0,0 +1,127 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <meta name="description" content="Expert System Terms of Service" />
+    <title>Terms of Service — Expert System</title>
+    <style>
+      body {
+        font:
+          17px/1.65 system-ui,
+          sans-serif;
+        color: #172033;
+        background: #f8fafc;
+        margin: 0;
+      }
+      main {
+        max-width: 760px;
+        margin: 0 auto;
+        padding: 48px 24px 72px;
+      }
+      h1,
+      h2 {
+        line-height: 1.2;
+      }
+      h1 {
+        font-size: 2.5rem;
+      }
+      h2 {
+        margin-top: 2em;
+        font-size: 1.35rem;
+      }
+      a {
+        color: #1d4ed8;
+      }
+      nav {
+        display: flex;
+        flex-wrap: wrap;
+        gap: 20px;
+      }
+      footer {
+        border-top: 1px solid #cbd5e1;
+        margin-top: 40px;
+        padding-top: 20px;
+      }
+    </style>
+  </head>
+  <body>
+    <main>
+      <nav aria-label="Main">
+        <a href="/">Expert System</a><a href="/privacy.html">Privacy</a
+        ><a href="/terms.html">Terms</a>
+      </nav>
+      <h1>Terms of Service</h1>
+      <p>Last updated: September 20, 2026</p>
+      <p>
+        These terms govern your use of Expert System, operated by STAR MODE,
+        including the website, API, and MCP plugins. By using the service, you
+        agree to these terms. If you do not agree, do not use the service.
+      </p>
+      <h2>Accounts and access</h2>
+      <p>
+        Use an account you are authorized to control, protect your credentials,
+        and keep account information accurate. Your agent may request read
+        access on your behalf. You are responsible for requests you authorize
+        and for complying with applicable laws and your organization’s rules. Do
+        not bypass access controls or usage limits, interfere with the service,
+        or access another person’s account without permission.
+      </p>
+      <h2>Data and permitted use</h2>
+      <p>
+        Expert System provides curated research and economic and financial
+        information. Third-party sources retain their rights. Access to a result
+        does not grant ownership or unrestricted redistribution rights; follow
+        the source’s applicable terms and retain attribution. Use the service
+        only for lawful purposes.
+      </p>
+      <h2>Accuracy and financial information</h2>
+      <p>
+        Data may be delayed, incomplete, revised, or incorrect. Generated
+        summaries and analysis may contain errors. Verify important claims
+        against original sources, including dates, units, and fiscal periods.
+        The service provides information, not personalized investment, legal, or
+        tax advice, and does not execute trades or guarantee investment
+        outcomes.
+      </p>
+      <h2>Plans and billing</h2>
+      <p>
+        Usage limits, prices, and billing intervals are displayed in the service
+        or at checkout. Paid subscriptions are governed by the terms shown at
+        purchase. Manage your subscription through your account; uninstalling a
+        plugin does not cancel it. Mandatory consumer rights remain applicable.
+      </p>
+      <h2>Availability and suspension</h2>
+      <p>
+        We may change features, data coverage, or limits, and the service may be
+        interrupted. We may restrict access for misuse, security concerns,
+        nonpayment, or legal requirements. You may stop using the service at any
+        time and contact us about account deletion.
+      </p>
+      <h2>Disclaimers and responsibility</h2>
+      <p>
+        To the extent permitted by applicable law, the service is provided as
+        available without warranties of accuracy, completeness, uninterrupted
+        availability, or fitness for a particular purpose. You are responsible
+        for decisions made using its outputs. Nothing in these terms excludes
+        rights or liabilities that cannot lawfully be excluded.
+      </p>
+      <h2>Privacy and changes</h2>
+      <p>
+        Our <a href="/privacy.html">Privacy Policy</a> explains data handling.
+        We may revise these terms and publish an updated date. Review changes
+        before continuing to use the service.
+      </p>
+      <h2>Contact</h2>
+      <p>
+        Contact STAR MODE through
+        <a href="https://github.com/starmode-base/expert-system/issues"
+          >Expert System support</a
+        >. For an account or privacy request, ask for a private contact channel
+        before providing identifying information. Do not post personal data,
+        credentials, or billing details in public issues.
+      </p>
+      <footer>STAR MODE · Expert System</footer>
+    </main>
+  </body>
+</html>

src/routes/api/v1.docs.ts

@@ -34,7 +34,7 @@ Connect an OAuth-capable HTTP MCP client to the canonical https://expert-system.
 
 Tool arguments use the same field names as REST, with native arrays for ids and a boolean for recent. Path parameters become tool arguments. POST arguments match the REST JSON body. Results are REST-equivalent JSON in structuredContent and serialized text; application failures set isError and include _meta.httpStatus (plus relevant HTTP headers in _meta.httpHeaders).
 
-MCP and REST share quotas and endpoint buckets. Authentication and validation failures, discovery, initialization and protocol errors are free. Valid tool calls, including catalogs, provider failures and partial results, count once. Current MCP and older Streamable HTTP clients share the stateless endpoint; OAuth and legacy HTTP+SSE are not supported.
+MCP and REST share quotas and endpoint buckets. Authentication and validation failures, discovery, initialization and protocol errors are free. Valid tool calls, including catalogs, provider failures and partial results, count once. Current MCP and older Streamable HTTP clients share the stateless endpoint; OAuth is required; legacy HTTP+SSE is not supported.
 
 ---