@ontrove/sdk 0.1.0 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,28 @@
 # @ontrove/sdk
 
+## 0.3.0
+
+### Minor Changes
+
+- dbf6fa1: Product-taxonomy renames: connectors are now **sources** (their per-feed
+  children are **feeds**), and hosted MCP servers are presented as **toolkits**.
+  No compatibility aliases.
+
+  - `@ontrove/sdk`: `defineConnector` → `defineSource`, `runConnector` →
+    `runSource`, `validateConnectorManifest` → `validateSourceManifest`,
+    `TroveConnector` → `TroveSource`, and `ConnectorDocument`/`ConnectorContext`/
+    `ConnectorSyncResult`/`ConnectorManifest`/`ConnectorContentType` →
+    `Source*`.
+  - `@ontrove/cli`: the `trove connector`/`trove connectors` command family is now
+    `trove source`/`trove sources`; `--connector` filter flags are now `--source`,
+    and the child-level `--source` flag is now `--feed` (`trove ingest --source
+<id> --feed <id>`). All GraphQL operations target the renamed schema
+    (`sources`, `source`, `createSource`, `addFeed`, `sourceId`/`feedId`,
+    `totalSources`, `documentsBySourceType`, …). The `trove mcp *` namespace is
+    unchanged.
+  - `@ontrove/mcp`: `ctx.trove.search`'s `TroveSearchOpts.connector` option is now
+    `source` (requires a Trove cloud that accepts the `source` wire key).
+
 ## 0.1.0
 
 Initial release — the connector authoring SDK: `defineConnector`, the `sync(ctx)`

package/README.md

@@ -1,18 +1,19 @@
 # @ontrove/sdk
 
-The thin standard library for authoring **Trove connectors**. You write a
-`sync(ctx)` that fetches from a source and returns documents; the SDK owns the
-document shape, the typed `ctx` capability object, the watermark/cursor model,
-the local-run harness the CLI drives, and manifest validation.
+The thin standard library for authoring **Trove sources** — the things that fill
+your Library. You write a `sync(ctx)` that fetches new content and returns
+documents; the SDK owns the document shape, the typed `ctx` capability object,
+the watermark/cursor model, the local-run harness the CLI drives, and manifest
+validation.
 
-It is symmetric with the hosted-MCP SDK
+It is symmetric with the toolkit-authoring SDK
 ([`@ontrove/mcp`](https://www.npmjs.com/package/@ontrove/mcp)) `defineMcpServer`
-contract: a connector returns documents to be _stored_ (batch `sync`); an MCP
-server returns tool results to be _read live_.
+contract: a source returns documents to be _stored_ (batch `sync`); a toolkit's
+tools return results to be _read live_.
 
-See the full [SDK Reference](https://docs.ontrove.sh/connectors/sdk-reference/),
-the [manifest.json reference](https://docs.ontrove.sh/connectors/manifest/), and
-the [cursors & sources model](https://docs.ontrove.sh/connectors/cursors-and-sources/)
+See the full [SDK Reference](https://docs.ontrove.sh/sources/sdk-reference/),
+the [manifest.json reference](https://docs.ontrove.sh/sources/manifest/), and
+the [cursors & feeds model](https://docs.ontrove.sh/sources/cursors-and-feeds/)
 in the docs.
 
 ## Install
@@ -23,16 +24,16 @@ npm install @ontrove/sdk
 
 ## Quickstart
 
-A connector's `index.ts` must `export default defineConnector(...)`. Your `sync`
-fetches from the source and returns documents — each field maps 1:1 onto the
+A source's `index.ts` must `export default defineSource(...)`. Your `sync`
+fetches new content and returns documents — each field maps 1:1 onto the
 `IngestDocumentInput` the Mac app pushes via `ingestDocuments`.
 
 ### Hacker News front page
 
 ```ts
-import { defineConnector } from '@ontrove/sdk';
+import { defineSource } from '@ontrove/sdk';
 
-export default defineConnector({
+export default defineSource({
   async sync(ctx) {
     const res = await ctx.fetch('https://hn.algolia.com/api/v1/search?tags=front_page');
     const { hits } = await res.json();
@@ -60,11 +61,11 @@ export default defineConnector({
 > `parseRss` / `stripHtml` below are **your own helpers** — the SDK ships no XML
 > parser. Bring your own (e.g. [`fast-xml-parser`](https://www.npmjs.com/package/fast-xml-parser)).
 
-```ts
-import { defineConnector } from '@ontrove/sdk';
+```ts no-typecheck
+import { defineSource } from '@ontrove/sdk';
 // import { parseRss, stripHtml } from './rss-helpers'; // your own — see note above
 
-export default defineConnector({
+export default defineSource({
   async sync(ctx) {
     const feedUrl = ctx.config.feedUrl as string;
     const since = ctx.cursor.type === 'date' ? new Date(ctx.cursor.value) : new Date(0);
@@ -101,9 +102,9 @@ A bare array is accepted too — `return documents;` is shorthand for
 | Member        | Type                                        | Description                                                                 |
 | ------------- | ------------------------------------------- | --------------------------------------------------------------------------- |
 | `ctx.config`  | `C` (typed preferences)                     | The user's setup preferences. **Never credentials.**                        |
-| `ctx.cursor`  | `Watermark` (read-only)                     | The source's current watermark; `{ type: 'none' }` on first sync.           |
+| `ctx.cursor`  | `Watermark` (read-only)                     | The feed's current watermark; `{ type: 'none' }` on first sync.             |
 | `ctx.fetch`   | `(url, init?) => Promise<Response>`         | Standard `fetch` — routes through the Mac app's networking.                 |
-| `ctx.log`     | `(...args) => void`                         | Structured log entry, surfaced in connector logs.                           |
+| `ctx.log`     | `(...args) => void`                         | Structured log entry, surfaced in the source's logs.                        |
 | `ctx.now`     | `() => Date`                                | Injected clock (deterministic under test).                                  |
 
 `ctx.credentials` (Keychain-resolved auth) and `ctx.browser` (Playwright) are
@@ -111,9 +112,9 @@ A bare array is accepted too — `return documents;` is shorthand for
 
 ## The document shape → `IngestDocumentInput`
 
-`ConnectorDocument` maps 1:1 onto the GraphQL `IngestDocumentInput` wire type:
+`SourceDocument` maps 1:1 onto the GraphQL `IngestDocumentInput` wire type:
 
-| `ConnectorDocument` | `IngestDocumentInput` | Required                       |
+| `SourceDocument`    | `IngestDocumentInput` | Required                       |
 | ------------------- | --------------------- | ------------------------------ |
 | `id`                | `externalId`          | **Yes**                        |
 | `title`             | `title`               | No                             |
@@ -126,27 +127,27 @@ A bare array is accepted too — `return documents;` is shorthand for
 | `metadata`          | `metadata` (JSON)     | No                             |
 | `contentType`       | `contentType`         | No (default `text`)            |
 
-Dedup is keyed on `(source, id)`, so `sync` is safe to retry — re-returning the
+Dedup is keyed on `(feed, id)`, so `sync` is safe to retry — re-returning the
 same `id` is skipped.
 
 ## Watermarks
 
-A `Watermark` describes how a source resumes between syncs:
+A `Watermark` describes how a feed resumes between syncs:
 
-- `{ type: 'date', value }` — time-ordered sources with "since &lt;date&gt;" filtering (RSS, most APIs).
+- `{ type: 'date', value }` — time-ordered feeds with "since &lt;date&gt;" filtering (RSS, most APIs).
 - `{ type: 'idSet', values, max? }` — monotonic ids, no reliable date filter.
 - `{ type: 'none' }` — re-fetch everything; rely on dedup. Always correct, less efficient.
 
 ## Local run harness
 
-`runConnector` is what `trove connector dev` / `trove connector test` call. It
+`runSource` is what `trove source dev` / `trove source test` call. It
 builds a `ctx`, runs `sync`, validates and dedups the documents:
 
-```ts
-import { runConnector } from '@ontrove/sdk';
-import connector from './index.js';
+```ts no-typecheck
+import { runSource } from '@ontrove/sdk';
+import source from './index.js';
 
-const { documents, cursor, duplicatesSkipped } = await runConnector(connector, {
+const { documents, cursor, duplicatesSkipped } = await runSource(source, {
   config: { feedUrl: 'https://example.com/feed.xml' },
   cursor: { type: 'date', value: '2026-06-01T00:00:00Z' },
 });
@@ -154,15 +155,15 @@ const { documents, cursor, duplicatesSkipped } = await runConnector(connector, {
 
 ## Manifest validation
 
-`validateConnectorManifest` backs `trove connector validate`. It checks required
+`validateSourceManifest` backs `trove source validate`. It checks required
 fields and the `id`/`version` patterns, and lints `config` for credential-shaped
 keys — the same spirit as the cloud's `validateConfig` (config holds preferences
 only; credentials live in the macOS Keychain).
 
-```ts
-import { validateConnectorManifest } from '@ontrove/sdk';
+```ts no-typecheck
+import { validateSourceManifest } from '@ontrove/sdk';
 
-const { valid, errors } = validateConnectorManifest(manifest);
+const { valid, errors } = validateSourceManifest(manifest);
 if (!valid) throw new Error(errors.join('\n'));
 ```
 

package/dist/define.d.ts

@@ -1,33 +1,33 @@
 /**
- * `defineConnector` — the single entry point for authoring a Trove connector
- * (connectors/sdk-reference). It is the symmetric sibling of `defineMcpServer`
+ * `defineSource` — the single entry point for authoring a Trove source
+ * (sources/sdk-reference). It is the symmetric sibling of `defineMcpServer`
  * in `@ontrove/mcp`.
  *
  * It is an identity function with light, eager validation: it confirms the value
- * is a connector object with a `sync` method, so a typo (`snyc`, a missing
+ * is a source object with a `sync` method, so a typo (`snyc`, a missing
  * `sync`, a non-function) fails at authoring/deploy time with a clear message
  * rather than at the first scheduled run. It does **not** execute `sync` — that is
- * {@link runConnector}'s job.
+ * {@link runSource}'s job.
  *
  * @module
  */
-import type { ConnectorContext, ConnectorDocument, ConnectorSyncResult, TroveConnector } from './types.js';
+import type { SourceContext, SourceDocument, SourceSyncResult, TroveSource } from './types.js';
 /**
- * Validate and return a connector definition unchanged.
+ * Validate and return a source definition unchanged.
  *
- * Using `defineConnector(...)` (rather than a bare `satisfies TroveConnector`)
- * gives an eager runtime check: the CLI calls this when loading a connector
+ * Using `defineSource(...)` (rather than a bare `satisfies TroveSource`)
+ * gives an eager runtime check: the CLI calls this when loading a source
  * module so a malformed export is rejected before any sync runs. The returned
  * value is the same object, with full inferred types preserved.
  *
- * @typeParam C - The shape of the connector's typed `ctx.config` preferences.
- * @param connector - The connector object to validate.
- * @returns The same connector object.
- * @throws {Error} If `connector` is not an object with a `sync` function.
+ * @typeParam C - The shape of the source's typed `ctx.config` preferences.
+ * @param source - The source object to validate.
+ * @returns The same source object.
+ * @throws {Error} If `source` is not an object with a `sync` function.
  *
  * @example
  * ```ts
- * export default defineConnector({
+ * export default defineSource({
  *   async sync(ctx) {
  *     const res = await ctx.fetch(ctx.config.feedUrl as string);
  *     return parseRss(await res.text());
@@ -35,15 +35,15 @@ import type { ConnectorContext, ConnectorDocument, ConnectorSyncResult, TroveCon
  * });
  * ```
  */
-export declare function defineConnector<C = Record<string, unknown>>(connector: TroveConnector<C>): TroveConnector<C>;
+export declare function defineSource<C = Record<string, unknown>>(source: TroveSource<C>): TroveSource<C>;
 /**
- * A connector authored inline as a single `sync` function, for the common case
- * where the connector has no other members. Equivalent to
- * `defineConnector({ sync })`.
+ * A source authored inline as a single `sync` function, for the common case
+ * where the source has no other members. Equivalent to
+ * `defineSource({ sync })`.
  *
- * @typeParam C - The shape of the connector's typed `ctx.config` preferences.
- * @param sync - The connector's `sync(ctx)` implementation.
- * @returns A validated {@link TroveConnector} wrapping `sync`.
+ * @typeParam C - The shape of the source's typed `ctx.config` preferences.
+ * @param sync - The source's `sync(ctx)` implementation.
+ * @returns A validated {@link TroveSource} wrapping `sync`.
  */
-export declare function defineSync<C = Record<string, unknown>>(sync: (ctx: ConnectorContext<C>) => Promise<ConnectorSyncResult | ConnectorDocument[]>): TroveConnector<C>;
+export declare function defineSync<C = Record<string, unknown>>(sync: (ctx: SourceContext<C>) => Promise<SourceSyncResult | SourceDocument[]>): TroveSource<C>;
 //# sourceMappingURL=define.d.ts.map

package/dist/define.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"define.d.ts","sourceRoot":"","sources":["../src/define.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EACV,gBAAgB,EAChB,iBAAiB,EACjB,mBAAmB,EACnB,cAAc,EACf,MAAM,YAAY,CAAC;AAEpB;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,eAAe,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACzD,SAAS,EAAE,cAAc,CAAC,CAAC,CAAC,GAC3B,cAAc,CAAC,CAAC,CAAC,CAQnB;AAED;;;;;;;;GAQG;AACH,wBAAgB,UAAU,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACpD,IAAI,EAAE,CAAC,GAAG,EAAE,gBAAgB,CAAC,CAAC,CAAC,KAAK,OAAO,CAAC,mBAAmB,GAAG,iBAAiB,EAAE,CAAC,GACrF,cAAc,CAAC,CAAC,CAAC,CAEnB"}
+{"version":3,"file":"define.d.ts","sourceRoot":"","sources":["../src/define.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,cAAc,EAAE,gBAAgB,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE/F;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,YAAY,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,EAAE,WAAW,CAAC,CAAC,CAAC,GAAG,WAAW,CAAC,CAAC,CAAC,CAQhG;AAED;;;;;;;;GAQG;AACH,wBAAgB,UAAU,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACpD,IAAI,EAAE,CAAC,GAAG,EAAE,aAAa,CAAC,CAAC,CAAC,KAAK,OAAO,CAAC,gBAAgB,GAAG,cAAc,EAAE,CAAC,GAC5E,WAAW,CAAC,CAAC,CAAC,CAEhB"}

package/dist/define.js

@@ -1,32 +1,32 @@
 /**
- * `defineConnector` — the single entry point for authoring a Trove connector
- * (connectors/sdk-reference). It is the symmetric sibling of `defineMcpServer`
+ * `defineSource` — the single entry point for authoring a Trove source
+ * (sources/sdk-reference). It is the symmetric sibling of `defineMcpServer`
  * in `@ontrove/mcp`.
  *
  * It is an identity function with light, eager validation: it confirms the value
- * is a connector object with a `sync` method, so a typo (`snyc`, a missing
+ * is a source object with a `sync` method, so a typo (`snyc`, a missing
  * `sync`, a non-function) fails at authoring/deploy time with a clear message
  * rather than at the first scheduled run. It does **not** execute `sync` — that is
- * {@link runConnector}'s job.
+ * {@link runSource}'s job.
  *
  * @module
  */
 /**
- * Validate and return a connector definition unchanged.
+ * Validate and return a source definition unchanged.
  *
- * Using `defineConnector(...)` (rather than a bare `satisfies TroveConnector`)
- * gives an eager runtime check: the CLI calls this when loading a connector
+ * Using `defineSource(...)` (rather than a bare `satisfies TroveSource`)
+ * gives an eager runtime check: the CLI calls this when loading a source
  * module so a malformed export is rejected before any sync runs. The returned
  * value is the same object, with full inferred types preserved.
  *
- * @typeParam C - The shape of the connector's typed `ctx.config` preferences.
- * @param connector - The connector object to validate.
- * @returns The same connector object.
- * @throws {Error} If `connector` is not an object with a `sync` function.
+ * @typeParam C - The shape of the source's typed `ctx.config` preferences.
+ * @param source - The source object to validate.
+ * @returns The same source object.
+ * @throws {Error} If `source` is not an object with a `sync` function.
  *
  * @example
  * ```ts
- * export default defineConnector({
+ * export default defineSource({
  *   async sync(ctx) {
  *     const res = await ctx.fetch(ctx.config.feedUrl as string);
  *     return parseRss(await res.text());
@@ -34,24 +34,24 @@
  * });
  * ```
  */
-export function defineConnector(connector) {
-    if (connector === null || typeof connector !== 'object') {
-        throw new Error('defineConnector: expected a connector object with a `sync` method');
+export function defineSource(source) {
+    if (source === null || typeof source !== 'object') {
+        throw new Error('defineSource: expected a source object with a `sync` method');
     }
-    if (typeof connector.sync !== 'function') {
-        throw new Error('defineConnector: connector must have a `sync(ctx)` function');
+    if (typeof source.sync !== 'function') {
+        throw new Error('defineSource: source must have a `sync(ctx)` function');
     }
-    return connector;
+    return source;
 }
 /**
- * A connector authored inline as a single `sync` function, for the common case
- * where the connector has no other members. Equivalent to
- * `defineConnector({ sync })`.
+ * A source authored inline as a single `sync` function, for the common case
+ * where the source has no other members. Equivalent to
+ * `defineSource({ sync })`.
  *
- * @typeParam C - The shape of the connector's typed `ctx.config` preferences.
- * @param sync - The connector's `sync(ctx)` implementation.
- * @returns A validated {@link TroveConnector} wrapping `sync`.
+ * @typeParam C - The shape of the source's typed `ctx.config` preferences.
+ * @param sync - The source's `sync(ctx)` implementation.
+ * @returns A validated {@link TroveSource} wrapping `sync`.
  */
 export function defineSync(sync) {
-    return defineConnector({ sync });
+    return defineSource({ sync });
 }

package/dist/index.d.ts

@@ -1,19 +1,20 @@
 /**
- * `@ontrove/sdk` — the thin standard library for authoring **Trove connectors**.
- * You write a `sync(ctx)` that fetches from a source and returns documents; the
+ * `@ontrove/sdk` — the thin standard library for authoring **Trove sources**.
+ * You write a `sync(ctx)` that fetches new content and returns documents; the
  * SDK owns the document shape (which maps 1:1 onto `IngestDocumentInput`), the
  * typed `ctx` capability object, the watermark/cursor model, the local-run
  * harness the CLI drives, and manifest validation.
  *
- * It is the symmetric sibling of `@ontrove/mcp`: a connector returns documents to
- * be _stored_ (`defineConnector` + `sync`); an MCP server returns tool results to
- * be _read live_ (`defineMcpServer`).
+ * It is the symmetric sibling of `@ontrove/mcp`, the toolkit-authoring library
+ * (every toolkit runs as a full MCP server on Trove's cloud): a source returns
+ * documents to be _stored_ (`defineSource` + `sync`); a toolkit's tools return
+ * results to be _read live_ (`defineMcpServer`).
  *
  * @example
  * ```ts
- * import { defineConnector } from '@ontrove/sdk';
+ * import { defineSource } from '@ontrove/sdk';
  *
- * export default defineConnector({
+ * export default defineSource({
  *   async sync(ctx) {
  *     const res = await ctx.fetch('https://hn.algolia.com/api/v1/search?tags=front_page');
  *     const { hits } = await res.json();
@@ -32,8 +33,8 @@
  *
  * @module
  */
-export { defineConnector, defineSync } from './define.js';
-export { isCredentialConfigKey, type ManifestValidationResult, validateConnectorManifest, } from './manifest.js';
-export { type RunOptions, type RunResult, runConnector, } from './runtime.js';
-export type { ConnectorContentType, ConnectorContext, ConnectorDocument, ConnectorManifest, ConnectorSyncResult, FetchLike, ManifestConfigField, TroveConnector, Watermark, } from './types.js';
+export { defineSource, defineSync } from './define.js';
+export { isCredentialConfigKey, type ManifestValidationResult, validateSourceManifest, } from './manifest.js';
+export { type RunOptions, type RunResult, runSource, } from './runtime.js';
+export type { FetchLike, ManifestConfigField, SourceContentType, SourceContext, SourceDocument, SourceManifest, SourceSyncResult, TroveSource, Watermark, } from './types.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAEH,OAAO,EAAE,eAAe,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAC1D,OAAO,EACL,qBAAqB,EACrB,KAAK,wBAAwB,EAC7B,yBAAyB,GAC1B,MAAM,eAAe,CAAC;AACvB,OAAO,EACL,KAAK,UAAU,EACf,KAAK,SAAS,EACd,YAAY,GACb,MAAM,cAAc,CAAC;AACtB,YAAY,EACV,oBAAoB,EACpB,gBAAgB,EAChB,iBAAiB,EACjB,iBAAiB,EACjB,mBAAmB,EACnB,SAAS,EACT,mBAAmB,EACnB,cAAc,EACd,SAAS,GACV,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAEH,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACvD,OAAO,EACL,qBAAqB,EACrB,KAAK,wBAAwB,EAC7B,sBAAsB,GACvB,MAAM,eAAe,CAAC;AACvB,OAAO,EACL,KAAK,UAAU,EACf,KAAK,SAAS,EACd,SAAS,GACV,MAAM,cAAc,CAAC;AACtB,YAAY,EACV,SAAS,EACT,mBAAmB,EACnB,iBAAiB,EACjB,aAAa,EACb,cAAc,EACd,cAAc,EACd,gBAAgB,EAChB,WAAW,EACX,SAAS,GACV,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -1,19 +1,20 @@
 /**
- * `@ontrove/sdk` — the thin standard library for authoring **Trove connectors**.
- * You write a `sync(ctx)` that fetches from a source and returns documents; the
+ * `@ontrove/sdk` — the thin standard library for authoring **Trove sources**.
+ * You write a `sync(ctx)` that fetches new content and returns documents; the
  * SDK owns the document shape (which maps 1:1 onto `IngestDocumentInput`), the
  * typed `ctx` capability object, the watermark/cursor model, the local-run
  * harness the CLI drives, and manifest validation.
  *
- * It is the symmetric sibling of `@ontrove/mcp`: a connector returns documents to
- * be _stored_ (`defineConnector` + `sync`); an MCP server returns tool results to
- * be _read live_ (`defineMcpServer`).
+ * It is the symmetric sibling of `@ontrove/mcp`, the toolkit-authoring library
+ * (every toolkit runs as a full MCP server on Trove's cloud): a source returns
+ * documents to be _stored_ (`defineSource` + `sync`); a toolkit's tools return
+ * results to be _read live_ (`defineMcpServer`).
  *
  * @example
  * ```ts
- * import { defineConnector } from '@ontrove/sdk';
+ * import { defineSource } from '@ontrove/sdk';
  *
- * export default defineConnector({
+ * export default defineSource({
  *   async sync(ctx) {
  *     const res = await ctx.fetch('https://hn.algolia.com/api/v1/search?tags=front_page');
  *     const { hits } = await res.json();
@@ -32,6 +33,6 @@
  *
  * @module
  */
-export { defineConnector, defineSync } from './define.js';
-export { isCredentialConfigKey, validateConnectorManifest, } from './manifest.js';
-export { runConnector, } from './runtime.js';
+export { defineSource, defineSync } from './define.js';
+export { isCredentialConfigKey, validateSourceManifest, } from './manifest.js';
+export { runSource, } from './runtime.js';

package/dist/manifest.d.ts

@@ -1,6 +1,6 @@
 /**
- * Connector manifest validation for `trove connector validate`
- * (see the connectors manifest reference).
+ * Source manifest validation for `trove source validate`
+ * (see the sources manifest reference).
  *
  * Two checks live here:
  *
@@ -8,7 +8,7 @@
  *    `id` pattern (`^[a-z0-9-]+$`), and well-formedness of `config`.
  * 2. **Credential-key lint** — the same spirit as the server-side
  *    `validateConfig` (`src/graphql/validate-config.ts`, invariant #6): a
- *    connector's `config` holds **user preferences only, never credentials**.
+ *    source's `config` holds **user preferences only, never credentials**.
  *    The cloud rejects writes whose config contains credential-shaped keys, so
  *    the SDK lints the manifest locally to catch the mistake before deploy. Auth
  *    material belongs in the (PROPOSED) `auth` block — surfaced from the macOS
@@ -28,7 +28,7 @@
  */
 export declare function isCredentialConfigKey(key: string): boolean;
 /**
- * The outcome of {@link validateConnectorManifest}.
+ * The outcome of {@link validateSourceManifest}.
  */
 export interface ManifestValidationResult {
     /** True when no errors were found. */
@@ -37,7 +37,7 @@ export interface ManifestValidationResult {
     errors: string[];
 }
 /**
- * Validate a connector `manifest.json` for `trove connector validate`.
+ * Validate a source `manifest.json` for `trove source validate`.
  *
  * Checks required fields and the `id`/`version` patterns, validates the `config`
  * descriptors, and runs the credential-key lint (rejecting credential-shaped
@@ -48,5 +48,5 @@ export interface ManifestValidationResult {
  * @param manifest - The parsed manifest object to validate.
  * @returns `{ valid, errors }` — `valid: true` with an empty `errors` array on success.
  */
-export declare function validateConnectorManifest(manifest: unknown): ManifestValidationResult;
+export declare function validateSourceManifest(manifest: unknown): ManifestValidationResult;
 //# sourceMappingURL=manifest.d.ts.map

package/dist/manifest.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"manifest.d.ts","sourceRoot":"","sources":["../src/manifest.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AA+CH;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAG1D;AAuCD;;GAEG;AACH,MAAM,WAAW,wBAAwB;IACvC,sCAAsC;IACtC,KAAK,EAAE,OAAO,CAAC;IACf,iEAAiE;IACjE,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,yBAAyB,CAAC,QAAQ,EAAE,OAAO,GAAG,wBAAwB,CAkCrF"}
+{"version":3,"file":"manifest.d.ts","sourceRoot":"","sources":["../src/manifest.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AA+CH;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAG1D;AAuCD;;GAEG;AACH,MAAM,WAAW,wBAAwB;IACvC,sCAAsC;IACtC,KAAK,EAAE,OAAO,CAAC;IACf,iEAAiE;IACjE,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,sBAAsB,CAAC,QAAQ,EAAE,OAAO,GAAG,wBAAwB,CAkClF"}

package/dist/manifest.js

@@ -1,6 +1,6 @@
 /**
- * Connector manifest validation for `trove connector validate`
- * (see the connectors manifest reference).
+ * Source manifest validation for `trove source validate`
+ * (see the sources manifest reference).
  *
  * Two checks live here:
  *
@@ -8,7 +8,7 @@
  *    `id` pattern (`^[a-z0-9-]+$`), and well-formedness of `config`.
  * 2. **Credential-key lint** — the same spirit as the server-side
  *    `validateConfig` (`src/graphql/validate-config.ts`, invariant #6): a
- *    connector's `config` holds **user preferences only, never credentials**.
+ *    source's `config` holds **user preferences only, never credentials**.
  *    The cloud rejects writes whose config contains credential-shaped keys, so
  *    the SDK lints the manifest locally to catch the mistake before deploy. Auth
  *    material belongs in the (PROPOSED) `auth` block — surfaced from the macOS
@@ -20,7 +20,7 @@
  * @module
  */
 /**
- * Credential-shaped key patterns that may NOT appear in a connector's `config`
+ * Credential-shaped key patterns that may NOT appear in a source's `config`
  * (invariant #6). Mirrors the authoritative cloud deny-list in
  * `src/graphql/validate-config.ts`. Matched case-insensitively and
  * separator-insensitively as substrings, so `apiKey`, `api_key`, `access_token`,
@@ -99,11 +99,11 @@ function validateConfigBlock(config, errors) {
     if (offending.length > 0) {
         const unique = [...new Set(offending)];
         errors.push(`manifest.config must not contain credential-shaped key(s): ${unique.join(', ')}. ` +
-            'Connector credentials belong in the macOS Keychain (declared as `auth`), not in `config`.');
+            'Source credentials belong in the macOS Keychain (declared as `auth`), not in `config`.');
     }
 }
 /**
- * Validate a connector `manifest.json` for `trove connector validate`.
+ * Validate a source `manifest.json` for `trove source validate`.
  *
  * Checks required fields and the `id`/`version` patterns, validates the `config`
  * descriptors, and runs the credential-key lint (rejecting credential-shaped
@@ -114,7 +114,7 @@ function validateConfigBlock(config, errors) {
  * @param manifest - The parsed manifest object to validate.
  * @returns `{ valid, errors }` — `valid: true` with an empty `errors` array on success.
  */
-export function validateConnectorManifest(manifest) {
+export function validateSourceManifest(manifest) {
     const errors = [];
     if (manifest === null || typeof manifest !== 'object' || Array.isArray(manifest)) {
         return { valid: false, errors: ['manifest must be a JSON object'] };

package/dist/runtime.d.ts

@@ -1,32 +1,32 @@
 /**
- * The local-run harness — what makes `trove connector dev` / `trove connector test`
- * work (connectors/sdk-reference; connectors/cursors-and-sources).
+ * The local-run harness — what makes `trove source dev` / `trove source test`
+ * work (sources/sdk-reference; the cursors guide).
  *
- * {@link runConnector} builds a {@link ConnectorContext} from a `{ config, cursor }`
+ * {@link runSource} builds a {@link SourceContext} from a `{ config, cursor }`
  * spec, invokes `sync(ctx)`, then normalizes and validates the result: it accepts
- * either a `ConnectorSyncResult` or a bare `ConnectorDocument[]`, deduplicates by
- * `id` (first occurrence wins, matching server-side `(source, id)` dedup), and
+ * either a `SourceSyncResult` or a bare `SourceDocument[]`, deduplicates by
+ * `id` (first occurrence wins, matching server-side `(feed, id)` dedup), and
  * validates every document's required fields, surfacing problems clearly instead
  * of pushing a malformed payload to the cloud.
  *
  * It is the symmetric sibling of `@ontrove/mcp`'s `dispatch`/`toFetchHandler`: that
- * runs a tool call end-to-end without the hosted runtime; this runs a connector
+ * runs a tool call end-to-end without the hosted runtime; this runs a source
  * sync end-to-end without the Mac app sync engine.
  *
  * @module
  */
-import type { ConnectorDocument, FetchLike, TroveConnector, Watermark } from './types.js';
+import type { FetchLike, SourceDocument, TroveSource, Watermark } from './types.js';
 /**
- * The options {@link runConnector} builds a `ctx` from. The CLI passes the
- * source's stored config and current cursor; tests inject `fetch`, `log`, and
- * `now` for determinism.
+ * The options {@link runSource} builds a `ctx` from. The CLI passes the
+ * source's stored config and the feed's current cursor; tests inject `fetch`,
+ * `log`, and `now` for determinism.
  *
- * @typeParam C - The shape of the connector's typed `ctx.config` preferences.
+ * @typeParam C - The shape of the source's typed `ctx.config` preferences.
  */
 export interface RunOptions<C = Record<string, unknown>> {
     /** The source's preference values (no credentials). Defaults to `{}`. */
     config?: C;
-    /** The source's current watermark. Defaults to `{ type: 'none' }`. */
+    /** The feed's current watermark. Defaults to `{ type: 'none' }`. */
     cursor?: Watermark;
     /** The fetch implementation to expose as `ctx.fetch`. Defaults to global `fetch`. */
     fetchImpl?: FetchLike;
@@ -36,13 +36,13 @@ export interface RunOptions<C = Record<string, unknown>> {
     now?: () => Date;
 }
 /**
- * The outcome of {@link runConnector}: the validated, deduped documents, the
+ * The outcome of {@link runSource}: the validated, deduped documents, the
  * resolved cursor, and the captured log lines. Mirrors enough of what the cloud
- * ingest reports for `trove connector test` to print a useful summary.
+ * ingest reports for `trove source test` to print a useful summary.
  */
 export interface RunResult {
     /** The validated, deduped documents `sync` returned. */
-    documents: ConnectorDocument[];
+    documents: SourceDocument[];
     /** The cursor `sync` returned, or `{ type: 'none' }` if it returned none. */
     cursor: Watermark;
     /** Captured `ctx.log(...)` lines (when no custom `logSink` was supplied). */
@@ -51,20 +51,20 @@ export interface RunResult {
     duplicatesSkipped: number;
 }
 /**
- * Run a connector's `sync` against a built `ctx` and collect/validate the result.
+ * Run a source's `sync` against a built `ctx` and collect/validate the result.
  *
- * This is the harness the CLI drives for `trove connector dev` / `trove connector
- * test`: it builds the {@link ConnectorContext} from `{ config, cursor }`, runs
+ * This is the harness the CLI drives for `trove source dev` / `trove source
+ * test`: it builds the {@link SourceContext} from `{ config, cursor }`, runs
  * `sync(ctx)`, normalizes a bare-array return, validates every document's
  * required fields (clear, indexed errors), and dedups by `id`. Errors thrown by
  * `sync` itself propagate unchanged so the CLI can report a failed run exactly as
  * the Mac app would.
  *
- * @typeParam C - The shape of the connector's typed `ctx.config` preferences.
- * @param connector - The connector whose `sync` to run.
+ * @typeParam C - The shape of the source's typed `ctx.config` preferences.
+ * @param source - The source whose `sync` to run.
  * @param options - The `{ config, cursor }` spec plus test injection points.
  * @returns The validated, deduped {@link RunResult}.
  * @throws {Error} If `sync` throws, returns a malformed value, or a document fails validation.
  */
-export declare function runConnector<C = Record<string, unknown>>(connector: TroveConnector<C>, options?: RunOptions<C>): Promise<RunResult>;
+export declare function runSource<C = Record<string, unknown>>(source: TroveSource<C>, options?: RunOptions<C>): Promise<RunResult>;
 //# sourceMappingURL=runtime.d.ts.map

package/dist/runtime.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"runtime.d.ts","sourceRoot":"","sources":["../src/runtime.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EAEV,iBAAiB,EAEjB,SAAS,EACT,cAAc,EACd,SAAS,EACV,MAAM,YAAY,CAAC;AAKpB;;;;;;GAMG;AACH,MAAM,WAAW,UAAU,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IACrD,yEAAyE;IACzE,MAAM,CAAC,EAAE,CAAC,CAAC;IACX,sEAAsE;IACtE,MAAM,CAAC,EAAE,SAAS,CAAC;IACnB,qFAAqF;IACrF,SAAS,CAAC,EAAE,SAAS,CAAC;IACtB,wFAAwF;IACxF,OAAO,CAAC,EAAE,CAAC,IAAI,EAAE,OAAO,EAAE,KAAK,IAAI,CAAC;IACpC,qEAAqE;IACrE,GAAG,CAAC,EAAE,MAAM,IAAI,CAAC;CAClB;AAED;;;;GAIG;AACH,MAAM,WAAW,SAAS;IACxB,wDAAwD;IACxD,SAAS,EAAE,iBAAiB,EAAE,CAAC;IAC/B,6EAA6E;IAC7E,MAAM,EAAE,SAAS,CAAC;IAClB,6EAA6E;IAC7E,IAAI,EAAE,OAAO,EAAE,EAAE,CAAC;IAClB,mEAAmE;IACnE,iBAAiB,EAAE,MAAM,CAAC;CAC3B;AA+ED;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,YAAY,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC5D,SAAS,EAAE,cAAc,CAAC,CAAC,CAAC,EAC5B,OAAO,GAAE,UAAU,CAAC,CAAC,CAAM,GAC1B,OAAO,CAAC,SAAS,CAAC,CAgCpB"}
+{"version":3,"file":"runtime.d.ts","sourceRoot":"","sources":["../src/runtime.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EACV,SAAS,EAET,cAAc,EAEd,WAAW,EACX,SAAS,EACV,MAAM,YAAY,CAAC;AAKpB;;;;;;GAMG;AACH,MAAM,WAAW,UAAU,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IACrD,yEAAyE;IACzE,MAAM,CAAC,EAAE,CAAC,CAAC;IACX,oEAAoE;IACpE,MAAM,CAAC,EAAE,SAAS,CAAC;IACnB,qFAAqF;IACrF,SAAS,CAAC,EAAE,SAAS,CAAC;IACtB,wFAAwF;IACxF,OAAO,CAAC,EAAE,CAAC,IAAI,EAAE,OAAO,EAAE,KAAK,IAAI,CAAC;IACpC,qEAAqE;IACrE,GAAG,CAAC,EAAE,MAAM,IAAI,CAAC;CAClB;AAED;;;;GAIG;AACH,MAAM,WAAW,SAAS;IACxB,wDAAwD;IACxD,SAAS,EAAE,cAAc,EAAE,CAAC;IAC5B,6EAA6E;IAC7E,MAAM,EAAE,SAAS,CAAC;IAClB,6EAA6E;IAC7E,IAAI,EAAE,OAAO,EAAE,EAAE,CAAC;IAClB,mEAAmE;IACnE,iBAAiB,EAAE,MAAM,CAAC;CAC3B;AA+ED;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,SAAS,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACzD,MAAM,EAAE,WAAW,CAAC,CAAC,CAAC,EACtB,OAAO,GAAE,UAAU,CAAC,CAAC,CAAM,GAC1B,OAAO,CAAC,SAAS,CAAC,CAgCpB"}