diff --git a/.agents/skills/create-pr/SKILL.md b/.agents/skills/create-pr/SKILL.md index 7d070e3..6838158 100644 --- a/.agents/skills/create-pr/SKILL.md +++ b/.agents/skills/create-pr/SKILL.md @@ -1,28 +1,20 @@ --- name: create-pr -description: Prepare or update a pull request with focused validation, current ADRs, and a complete PR update record. +description: Create or update a documentation PR without publishing internal engineering records. --- -# Create or update a pull request +# Create or update a documentation PR -## Repository documentation requirements +Follow [docs/README.md](../../../docs/README.md). Do not create, copy, commit, or +publish `docs/adrs/` or `docs/updates/`, including templates and historical files. +Keep architecture decisions and complete update records in the owning source +repository; record docs-only changes and validation in the PR body. -Follow [docs/README.md](../../../docs/README.md) for every change in this workflow. Create or update -ADRs for resolved durable decisions, keep affected README/setup/public docs current, -and maintain the complete pending or PR-numbered update record after every revision. -Use the shared templates and section names. Missing or stale required documentation -blocks completion. Document already authorized decisions without asking again; ask -only about unresolved choices. These requirements govern documentation instructions -elsewhere in this skill; preserve its repository-specific implementation and checks. +Inspect the actual base and preserve unrelated work. Verify public claims and +examples against source contracts, and update affected guides, setup instructions, +and navigation. Link companion API/SDK PRs and explain deployment order. -Inspect the actual base branch, current diff, existing PR, and unrelated workspace -changes. Complete authorized implementation and focused repository checks before -publishing. Follow `pre-commit-checks` and `maintain-docs`; include affected ADRs, -README/setup/public docs, and the pending update record in the reviewed diff. - -When publishing is authorized, intentionally stage the task files, commit, push, -and open or update a draft PR. Read its actual number/URL, rename the pending record -to `docs/updates/.md`, update its contents, and push it to the same PR. Link -that record and relevant ADRs/related PRs in the description. Recheck the full diff, -validation, and documentation after later review or rebase changes. Never include -unrelated work, secret values, or unverified claims. Do not merge unless authorized. +Run `npm run check:publication-boundary`, `mint validate`, `mint broken-links`, +`mint a11y`, and `git diff --check`. Report actual results and remaining external +publication work. When authorized, commit/push the reviewed files and create or +update the PR; do not add a PR-numbered update file. Merge only when authorized. diff --git a/.agents/skills/maintain-docs/SKILL.md b/.agents/skills/maintain-docs/SKILL.md index d0888ee..84874cf 100644 --- a/.agents/skills/maintain-docs/SKILL.md +++ b/.agents/skills/maintain-docs/SKILL.md @@ -1,23 +1,20 @@ --- name: maintain-docs -description: Maintain repository ADRs, change and PR update records, and affected setup/public docs while implementing or reviewing changes. +description: Maintain public documentation without publishing internal engineering records. --- -# Maintain repository documentation +# Maintain public documentation -Follow [docs/README.md](../../../docs/README.md), the shared documentation contract. -Read governing ADRs before implementation. Write accepted durable decisions in -`docs/adrs/`; amend current text and append timestamped history when they change. -Record already authorized decisions directly and ask only about unresolved choices. +Follow [docs/README.md](../../../docs/README.md). Do not create, copy, commit, or +publish `docs/adrs/` or `docs/updates/`, including templates and historical files. +Keep architecture decisions and complete update records in the owning source +repository; record docs-only changes and validation in the PR body. -Keep one complete update record using [the template](../../../docs/updates/template.md). -Before a PR exists, use `docs/updates/pending/.md`. After the authorized -PR is opened, rename it to `docs/updates/.md` using the verified -number and URL. Refresh it after each revision; never invent a number or publish -solely to obtain one. +Inspect the actual base and preserve unrelated work. Verify public claims and +examples against source contracts, and update affected guides, setup instructions, +and navigation. Link companion API/SDK PRs and explain deployment order. -Review affected READMEs, setup/deployment instructions, generated contracts, and -public documentation. Update them in the same change, linking related repository -records and deployment order when applicable. Before handoff, compare the docs with -the complete final diff and report actual validation and remaining work. Missing -or stale required documentation blocks completion. Release notes remain separate. +Run `npm run check:publication-boundary`, `mint validate`, `mint broken-links`, +`mint a11y`, and `git diff --check`. Report actual results and remaining external +publication work. When authorized, commit/push the reviewed files and create or +update the PR; do not add a PR-numbered update file. Merge only when authorized. diff --git a/.agents/skills/pre-commit-checks/SKILL.md b/.agents/skills/pre-commit-checks/SKILL.md index 5033092..a6563f5 100644 --- a/.agents/skills/pre-commit-checks/SKILL.md +++ b/.agents/skills/pre-commit-checks/SKILL.md @@ -1,26 +1,20 @@ --- name: pre-commit-checks -description: Validate the affected diff and required documentation before committing or completing a pull request. +description: Validate public documentation without publishing internal engineering records. --- -# Pre-commit checks +# Validate public documentation -## Repository documentation requirements +Follow [docs/README.md](../../../docs/README.md). Do not create, copy, commit, or +publish `docs/adrs/` or `docs/updates/`, including templates and historical files. +Keep architecture decisions and complete update records in the owning source +repository; record docs-only changes and validation in the PR body. -Follow [docs/README.md](../../../docs/README.md) for every change in this workflow. Create or update -ADRs for resolved durable decisions, keep affected README/setup/public docs current, -and maintain the complete pending or PR-numbered update record after every revision. -Use the shared templates and section names. Missing or stale required documentation -blocks completion. Document already authorized decisions without asking again; ask -only about unresolved choices. These requirements govern documentation instructions -elsewhere in this skill; preserve its repository-specific implementation and checks. +Inspect the actual base and preserve unrelated work. Verify public claims and +examples against source contracts, and update affected guides, setup instructions, +and navigation. Link companion API/SDK PRs and explain deployment order. -Inspect the complete task diff and preserve unrelated changes. Read the repository -instructions and run checks appropriate to the affected components. Fix in-scope -failures and distinguish pre-existing failures and unavailable external checks. - -Follow `maintain-docs` before handoff: review governing ADRs, update durable decisions, -keep affected README/setup/public docs accurate, and refresh the current update -record. A missing or stale required record blocks completion. Check formatting, -links, generated artifacts, release-note obligations, and the final diff. Report -only checks actually run; do not publish or merge without existing authorization. +Run `npm run check:publication-boundary`, `mint validate`, `mint broken-links`, +`mint a11y`, and `git diff --check`. Report actual results and remaining external +publication work. When authorized, commit/push the reviewed files and create or +update the PR; do not add a PR-numbered update file. Merge only when authorized. diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index f8d6b09..f314819 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -1,15 +1,17 @@ -## Change +## Changes -Describe the problem and resulting behavior. +Describe the public documentation changes and their source contracts. ## Validation -Record checks actually run, their results, and any unverified flows. +- [ ] `npm run check:publication-boundary` +- [ ] `mint validate` +- [ ] `mint broken-links` +- [ ] `mint a11y` +- [ ] `git diff --check` -## Documentation +## Publication and related changes -- Link the current `docs/updates/.md` record (rename the pending record after PR creation). -- Link new or amended ADRs under `docs/adrs/`, or state `ADR review: no new decision` with a reason. -- List affected README, setup/deployment, and public documentation changes; link related repository PRs and merge order. -- Confirm the update record describes the full current diff, actual validation, and required consumer/operator actions. -- Refresh this section and the same update record after subsequent review or rebase changes. +Link companion API/SDK PRs and explain deployment order or remaining release work. +Internal ADRs and update records belong in those source repositories. Do not add +`docs/adrs/` or `docs/updates/` files to this repository. diff --git a/.github/workflows/publication-boundary.yml b/.github/workflows/publication-boundary.yml new file mode 100644 index 0000000..19506e4 --- /dev/null +++ b/.github/workflows/publication-boundary.yml @@ -0,0 +1,14 @@ +name: Public documentation boundary +on: + pull_request: + push: + branches: [main] +jobs: + publication-boundary: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - uses: actions/setup-node@v4 + with: + node-version: 24 + - run: npm run check:publication-boundary diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..c7289cd --- /dev/null +++ b/.gitignore @@ -0,0 +1,4 @@ + +# Internal engineering records belong in the owning source repository. +/docs/adrs/ +/docs/updates/ diff --git a/.mintignore b/.mintignore index c5fd3fb..f20b90c 100644 --- a/.mintignore +++ b/.mintignore @@ -7,5 +7,8 @@ AGENTS.md drafts/ *.draft.mdx -# Internal repository decision and change records +# Internal maintenance policy; ADRs and update records are prohibited here. docs/ + +docs/adrs/** +docs/updates/** diff --git a/AGENTS.md b/AGENTS.md index 6182f34..2dee9ef 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -2,16 +2,16 @@ This is the canonical Mintlify documentation repository for Tilde. Public guides live in the root MDX pages and feature/guide directories; `docs.json` owns navigation. -Internal architecture and PR records live under `docs/adrs` and `docs/updates` and -are excluded from site publication by `.mintignore`. +Architecture decisions and detailed change records belong in the owning source +repository, never in this public docs repository. ## Documentation maintenance -For every change, follow [docs/README.md](docs/README.md) and -[maintain-docs](.agents/skills/maintain-docs/SKILL.md). Read governing ADRs, record -resolved durable decisions, maintain the current pending/PR-numbered update record, -and keep affected public pages and navigation synchronized. Do not ask again about -already-authorized decisions or preserve obsolete setup prompts. +Follow [docs/README.md](docs/README.md). Never create, copy, commit, or publish +`docs/adrs/` or `docs/updates/`, including historical records or templates. +Record docs-only intent, verification, and publication requirements in the PR +body. Link source-repository decisions/PRs when useful. Keep public pages, +examples, setup instructions, and navigation synchronized. ## Public content @@ -30,6 +30,6 @@ already-authorized decisions or preserve obsolete setup prompts. ## Validation and publication Run `mint validate`, `mint broken-links`, and `mint a11y` after content/navigation -changes. Review the final diff and keep the same update record current through PR +changes. Run `npm run check:publication-boundary` and review the final diff through PR revisions. Use the [create-pr workflow](.agents/skills/create-pr/SKILL.md) when PR publication is authorized; never fabricate a PR number or claim a deployment. diff --git a/README.md b/README.md index 308ba06..a931425 100644 --- a/README.md +++ b/README.md @@ -66,6 +66,14 @@ Install Mintlify's documentation skill for your coding tools: npx skills add https://mintlify.com/docs ``` +## Internal records + +Never store or publish `docs/adrs/` or `docs/updates/` in this repository. Keep +engineering decisions and change records in the owning source repository; use +this repository's PR descriptions for docs-only rationale and validation. Run +`npm run check:publication-boundary` before publishing. See [the publication +policy](docs/README.md). + ## Publishing changes Mintlify deploys committed changes through its GitHub app. Generated tool-provider files must be committed because Mintlify maps indexable routes to MDX files in the repository. diff --git a/chatkit.mdx b/chatkit.mdx index b43a6ca..403a64e 100644 --- a/chatkit.mdx +++ b/chatkit.mdx @@ -31,6 +31,8 @@ Signal provider instances and rules may also be personal. A personal rule names Signal providers and rules use the same two planes. Visibility controls discovery and delivery inspection; ownership controls configuration, target/session policy, grants, state-changing retries, and deletion. Deliveries and sessions inherit the rule and target authorization rather than defining independent grants. +Build a customer-hosted integration with [custom ChatKit providers](/custom-chatkit-providers). Definitions are reusable within a team, and each connection has independent credentials and configuration. + ## Set up ChatKit diff --git a/custom-chatkit-providers.mdx b/custom-chatkit-providers.mdx new file mode 100644 index 0000000..425bb66 --- /dev/null +++ b/custom-chatkit-providers.mdx @@ -0,0 +1,164 @@ +--- +title: "Custom ChatKit providers" +description: "Host your own chat integration with the TypeScript SDK." +icon: "plug" +--- + +A custom ChatKit provider connects your platform to Tilde's canonical sessions, +agent execution, and durable delivery. You host the provider backend. Tilde +stores a reusable, team-scoped definition and creates an independent connection +for each configured account. + +Your backend verifies external webhook signatures, interprets platform threads +and identities, and converts messages. Tilde owns authorization, conversation +participants, tool-execution records, and delivery retries. Provider runtime +credentials cannot act as Tilde users. + +## Register and connect + +1. Open **ChatKit → Configure providers** and register the backend's HTTPS + discovery URL. Registration creates a pending definition and returns its + signing key once. +2. Configure that key and the returned definition ID in your backend, then + refresh discovery. A failed refresh preserves the last valid manifest and + records diagnostics. Changes incompatible with existing connections require + a new definition. +3. Choose the provider in the generic setup catalog. Configure the connection's + default agent, credentials, and platform settings. The backend can request + forms, authorization redirects, or setup instructions. Use **Inspect connections** + to configure a pending imported connection or resume interrupted setup. +4. Send external webhooks directly to your backend. Verify the platform's raw + request before submitting normalized events to Tilde. + +You can also manage definitions through `client.chatkit.customProviders`: + +```typescript +const registration = await client.chatkit.customProviders.create({ + displayName: "My chat platform", + discoveryUrl: "https://provider.example/provider", +}); +// Store registration.signingKey in your backend's secret manager. +// Configure registration.provider.id as the endpoint's definitionId. +await client.chatkit.customProviders.refresh({ + providerId: registration.provider.id, +}); +``` + +Use `startConnection` and `resumeConnection` for SDK-driven setup. Their +`nextAction` describes the next generic setup step. Responses may contain +one-time secret outputs; keep those out of transcripts and application logs. + +## Author a backend + +Import `defineChatKitProvider`, `chatKitProviderEndpoint`, and +`createProviderRuntimeClient` from `@trytilde/sdk/chatkit-provider`. +The endpoint uses standard `Request` and `Response` objects and does not require +Vercel AI. Export its `GET` handler for discovery and `POST` handler for signed +operations. + +Your definition declares configuration schemas, authentication methods, +subscriptions, content capabilities, and session tools. Implement the matching +setup, identity, messaging, and tool handlers. Declare only supported +capabilities. The SDK validates manifests and verifies Tilde's operation +signature before invoking your code. + +A signed operation binds the protocol version, request ID, definition, +connection, and execution context. Configuration and managed credentials arrive +only at authorized backend operations. For OAuth, verify the platform callback +and redirect the browser to the supplied `input.return_url`. It carries Tilde's +persisted setup binding; the dashboard resumes that setup as the signed-in user. +Store connection runtime tokens securely; +use `setup.credentialsUpdated` to handle rotation. + +Dispatch's `packages/sdk/examples/custom-chatkit` directory contains Linq and +AgentMail adapters, a runnable Node host, and a custom streaming protocol. +Linq covers line selection, subscriptions, reactions, thread reads, and polls. +AgentMail covers inbox credentials, email threading, rich recipients, HTML, +reply-all, and attachments. + +## Ingest messages and identities + +Use a connection-scoped runtime client to ensure a conversation and ingest a +normalized message. Event IDs, external identities, and conversation keys are +scoped to the connection, so two accounts can safely reuse the same external +IDs. Tilde durably accepts each event and rejects conflicting reuse of an ID. +Polling and socket consumers use the same API as webhook handlers. + +The runtime client supports attachment uploads and downloads, external +participant updates, history, agent address registration, and mention +normalization. External addresses are delivery identities; adding one never +grants Tilde-user access. Upload attachments before referencing their IDs in +an inbound message. + +## Session tools + +Declare contextual tools such as `addReaction`, `getThread`, or your platform's +own actions. Discovery can narrow the declaration based on the current +connection and participants. Tilde intersects the result with the authenticated +agent's actual turn and target authorization. + +Agents discover bound tools with `client.chatkit.sessionTools({ sessionId })`. +The Vercel AI adapter exposes `context.session.tools` and a standalone +`sessionProviderTools` helper. Session-scoped MCP exposes provider actions with +the `chatkit_provider__` prefix. Common canonical names such as `sendMessage` +cannot be shadowed. + +Keep the model's tool-call ID stable across retries. Tilde binds the agent, +session, target, trigger, connection, and execution ID outside model arguments. +Each mutation must support reconciliation. Return `applied` with its result, +`absent` only when a retry is safe, or `uncertain` when the outcome is unknown. +A missing local receipt alone does not prove that the platform operation failed. + +## Rich delivery + +`sendMessage` stores one canonical message and durable delivery intent. +Providers prepare private delivery options and deliver the persisted output. +Automatic replies and explicit sends use the same delivery worker. + +To/CC/BCC, subject, HTML, reply-all, and provider-specific options do not need to +be reconstructed from visible text. Tilde encrypts the private delivery +envelope. BCC stays out of shared transcripts, participant lists, realtime +payloads, and ordinary execution records. The email reference supports `provider_options: { new_thread: true }` with +explicit To recipients when starting a new email from an authorized session +turn. Providers must also redact BCC from +their own tool results and inbound extension data. + +Use the supplied delivery ID for platform idempotency or delivery markers. +Reconciliation runs before retrying an uncertain send. Attachment URLs are +refreshed for delivery attempts. Exhausted retries remain visible as dead letters. Use +`client.chatkit.customProviders.listConnectionWork` to inspect ingestion and +cleanup status without reading message payloads. After correcting a backend +failure, use `retryConnectionWork` with the returned work ID. + +## Client transports + +Custom client protocols can submit canonical turns, read history, and subscribe +to `client.chatkit.streamSessionEvents`. Authenticate each caller with their +own SDK client. Reconnect with the last event cursor and use history for a fresh +snapshot. Tilde filters events by the current audience and periodically +revalidates stream authorization. + +A provider runtime token is for external platform operations. It cannot +impersonate a user or replace caller authentication for a streaming client. + +## Lifecycle and portability + +Disabling a definition pauses its connections' runtime work and pending +delivery. Re-enabling resumes them. Deleting a connection revokes its runtime +credential, cancels pending delivery, and schedules external cleanup while +retaining conversation history. A referenced definition cannot be deleted. + +Setup can provision an associated custom Tools backend through the existing +Tools lifecycle. The connection owns its typed toolkit reference and cleans it +up on deletion. Tools retain their own enablement settings; session tools do +not require a separate toolkit instance. + +State exports include public definitions, connection configuration, and +portable agent/toolkit references. Imports require discovery and credential +rebinding before runtime activation. Credentials, runtime tokens, pending work, +and private setup continuation are not portable state. + +Deploy additive API support and upgrade workers before enabling custom +providers or releasing an SDK that uses these operations. Use public HTTPS or a +reachable Dev Tunnel; a local-development flag does not grant private-network +access. diff --git a/docs.json b/docs.json index eaabba2..2542cbb 100644 --- a/docs.json +++ b/docs.json @@ -131,6 +131,7 @@ ] }, "chatkit", + "custom-chatkit-providers", "memory", "skills", "dev-tunnels", diff --git a/docs/README.md b/docs/README.md index 158f152..4272862 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,50 +1,20 @@ -# Repository documentation - -This convention applies to every change in this repository, including documentation, -configuration, dependencies, generated contracts, and changes made during review. - -## Required workflow - -1. Read the relevant `docs/adrs/` records before changing their decisions. Keep the - owning README, setup/deployment guide, and public documentation accurate in the - same change. Link related repositories when a change crosses their boundaries. -2. Review every change for durable architecture, security, tenancy, public contract, - storage, deployment, or product decisions. Create or update an ADR when one changes. - Record already authorized decisions directly; ask only about unresolved choices. - For changes with no durable decision, state `ADR review: no new decision` and why - in the update record. Do not create empty ADRs for routine edits. -3. Maintain one update record for the complete change, not one per commit. Before a - PR number exists, use `docs/updates/pending/.md`. Once a PR is opened, - rename it to `docs/updates/.md` and fill in its verified PR URL. - Never guess a PR number or open a PR solely to satisfy this documentation rule. -4. Refresh that same record after implementation, documentation, review, rebase, or - conflict-resolution changes. Before handing off or marking a PR ready, compare - the record with the final diff and report any remaining validation or release work. - -## Records and templates - -- [Architecture decisions](adrs/README.md): `docs/adrs/NNNN-short-slug.md`. -- [Change and PR updates](updates/README.md): `docs/updates/.md`. -- [ADR template](adrs/template.md) and [update template](updates/template.md). - -Keep accepted decision history. When a decision changes, update its current text and -append an ISO-8601 timestamped entry under `Updates`, or write a superseding ADR and -link both records. Do not erase previous rationale or amendment entries. - -Update records describe the current result, verification, and required consumer or -operator actions. Use the same four sections in every repository: `Intent of the -change`, `Architecture changes`, `Summarized changes`, and `Critical to apply`. -Include a small Mermaid boundary/flow diagram in `Architecture changes`; for a -non-architectural change, show the affected documentation or component boundary and -explicitly say the runtime architecture is unchanged. Start `Critical to apply` with -an exact `yes` or `no` on its own line, then explain why. - -Do not claim checks that were not run or treat simulated provider checks as live -verification. Keep secrets, private conversations, raw task transcripts, personal -data, screenshots, generated deployment state, and local configuration out of -these records. Link safe evidence and public contracts instead. - -Documentation records complement release notes and generated API documentation; -Changesets, Changie, or other repository release processes still apply. Historical -records keep their original filenames and format; use this convention for new or -actively updated work. Plans and speculative backlogs are not accepted ADRs. +# Documentation publication boundary + +This repository contains public Tilde documentation. Do not create, copy, commit, +or publish ADRs or PR/change update records here. In particular, `docs/adrs/` and +`docs/updates/` must remain absent, including historical records and templates. + +Keep durable architecture decisions and detailed change records in the owning +API, Dispatch, or other source-code repository. Link their PRs or records from +this repository's PR description when useful. Describe docs-only rationale, +validation, and publication requirements in the PR description itself. + +For each change, verify public examples against their owning API/SDK contracts, +update affected guides/navigation/setup instructions, and run +`npm run check:publication-boundary`, `mint validate`, `mint broken-links`, and +`mint a11y`. The publication guard rejects tracked or local internal-record +folders; `.mintignore` independently excludes internal repository documentation. + +This policy supersedes the earlier requirement to keep ADRs and PR-numbered +update records in the documentation repository. Source repositories retain their +own record-maintenance requirements. diff --git a/docs/adrs/0001-repository-documentation-convention.md b/docs/adrs/0001-repository-documentation-convention.md deleted file mode 100644 index 4372aa6..0000000 --- a/docs/adrs/0001-repository-documentation-convention.md +++ /dev/null @@ -1,29 +0,0 @@ -# ADR-0001: Shared repository documentation convention - -Status: Accepted - -## In brief - -- Use `docs/adrs` for durable decisions and `docs/updates` for complete change records. -- Apply the same templates and maintenance requirements across Tilde repositories. - -## Context - -Repository instructions differed in directory names, templates, and whether changes -required updated records. That made accepted decisions and release obligations easy -to lose between implementation and review. - -## Decision - -Adopt [the shared documentation workflow](../README.md) as requested on 2026-09-07. -Agents and PR/pre-commit skills must maintain required records as part of the change. -Draft a pending update before a PR exists, then rename it using the actual PR number. -Record decisions already authorized in the task without asking for duplicate approval. - -## Consequences - -Existing ADR identifiers and amendment history remain intact. References to the old -singular directory are updated. Each repository owns its facts; shared structure does -not mean copying another repository's architecture. Release notes and public guides -remain separate obligations. Supporting indexes/templates and pending change records -are part of the documentation setup. diff --git a/docs/adrs/README.md b/docs/adrs/README.md deleted file mode 100644 index 2d9338e..0000000 --- a/docs/adrs/README.md +++ /dev/null @@ -1,18 +0,0 @@ -# Architecture decision records - -Follow [the repository documentation workflow](../README.md) for every change. -ADRs record durable decisions and the reasoning a future maintainer needs. - -Use the next unused sequential number in `NNNN-short-slug.md`; keep existing IDs -stable. Start from [template.md](template.md), remove instructions, and write concise -normal prose. Include context, the decision, meaningful alternatives/consequences, -and a Mermaid diagram when a relationship benefits from one. Do not add decorative -sections or diagrams. - -Record an already approved decision without asking for approval again. Ask only -when the underlying choice is unresolved. If no durable decision changed, explain -that in the change's update record instead of creating an empty ADR. - -When amending an ADR, preserve earlier history and append a chronological bullet -under `Updates`: `- YYYY-MM-DDTHH:mm:ssZ: What changed and why.` Use a new ADR when -superseding a decision would otherwise obscure its rationale, and link both records. diff --git a/docs/adrs/template.md b/docs/adrs/template.md deleted file mode 100644 index 6ecba9c..0000000 --- a/docs/adrs/template.md +++ /dev/null @@ -1,23 +0,0 @@ -# ADR-NNNN: Decision title - -Status: Accepted - -## In brief - -- State the decision and the boundary it establishes. - -## Context - -Explain the concrete problem and why the choice needs durable reasoning. - -## Decision - -Describe the accepted behavior and its owner. Link relevant contracts or records. -Add a small Mermaid diagram only when it clarifies the relationship. - -## Consequences - -Explain the material benefit, cost, alternatives rejected, and migration impact. - -Add an Updates section only when this record is later amended. Preserve previous -entries and use ISO-8601 timestamps. Remove these template instructions. diff --git a/docs/updates/34.md b/docs/updates/34.md deleted file mode 100644 index d24b37b..0000000 --- a/docs/updates/34.md +++ /dev/null @@ -1,46 +0,0 @@ -# Identity documentation and frontend chat setup - -PR: https://github.com/trytilde/docs/pull/34 - -## Intent of the change - -Document independent application authentication, org-owned identities, proxy token setup, managed linking, and a same-origin frontend chat UI. - -## Architecture changes - -Governing decision: [0001-repository-documentation-convention](../adrs/0001-repository-documentation-convention.md). -This repository documents the identity/authentication contracts implemented by Tilde API and the SDK. Its own runtime architecture is unchanged. - -```mermaid -flowchart LR - Agent["Agent and PR workflows"] --> Convention["docs/README.md"] - Convention --> Decisions["docs/adrs"] - Convention --> Updates["docs/updates"] - Convention --> Guides["Owning README and public guides"] -``` - -## Summarized changes - -- Documented native first-org/team setup and invitation-directed signup, with account-only Clerk lifecycle webhooks. -- Updated identity and membership examples to cursor pagination. -- Reconciled upstream CLI naming and agent-key terminology while retaining the new delegation guidance. -- Added a dedicated Identities navigation section for overview/provisioning, proxy tokens, and managed account linking. -- Documented reviewed identity membership/identifier management, strict suspension recovery, safe proxy transport, and the signed original-event reset cutoff. -- Added frontend chat setup covering trusted sessions, private session creation, streaming, uploads, and realtime tickets. -- Linked the guide from Quickstart and ChatKit and refreshed package names. -- Added shared repository documentation/PR conventions; internal records are excluded from Mintlify publication. -- Validation: Mintlify build validation, broken-link checks, and accessibility checks passed again after reconciling current upstream documentation. -- Independent review checked identity/proxy/linking examples against the owning SDK/API source and scanned the added diff for credential-shaped values; no exposure was found. - -## Critical to apply - -yes - -Publish alongside the matching Tilde API/SDK/HeyAsh release. Examples require the SDK proxy/identity exports and configured application credentials; they must not be presented as supported by an older deployed API. - -Coordinated implementation: [API 275](https://github.com/trytilde/api/pull/275), -[SDK 153](https://github.com/trytilde/dispatch/pull/153), -[HeyAsh 6](https://github.com/trytilde/heyash/pull/6), and -[Clerk configuration 88](https://github.com/trytilde/infrastructure-terraform/pull/88). -Merging documentation does not establish that the matching application release -or reset has been deployed. diff --git a/docs/updates/35.md b/docs/updates/35.md deleted file mode 100644 index 5eb54e9..0000000 --- a/docs/updates/35.md +++ /dev/null @@ -1,39 +0,0 @@ -# Distinguish initial organization setup from account recovery - -PR: https://github.com/trytilde/docs/pull/35 - -## Intent of the change - -Correct the identities guide so accounts that already completed organization -onboarding are not told to create another first organization after losing their -remaining memberships. - -## Architecture changes - -ADR review: no new decision. This clarification documents the existing account -recovery and replay-protection behavior in [API PR 275](https://github.com/trytilde/api/pull/275) -and its governing [API ADR 23](https://github.com/trytilde/api/blob/codex/org-runtime-identities/docs/adrs/0023-org-runtime-identities-and-proxy-delegation.md). -This documentation repository's runtime architecture is unchanged. - -```mermaid -flowchart LR - Account["Account without membership"] --> First["First-time: organization and team setup"] - Account --> Existing["Previously completed setup: access recovery"] - Existing --> Recovery["Invitation, managed linking, or sign-out"] -``` - -## Summarized changes - -- Restricted first-organization wizard guidance to first-time accounts. -- Documented the Restore organization access screen for accounts whose organization onboarding was already completed. -- Preserved invitation-directed signup and managed linking, and clarified that retries do not recreate deleted organizations or restore revoked access. -- Compared the wording with the API account-onboarding component and ADR; API and HeyAsh files were not changed. -- Validation: `mint validate`, `mint broken-links`, `mint a11y`, and `git diff --check` passed. - -## Critical to apply - -no - -This documentation clarification introduces no migration or configuration change. -The behavior belongs to the coordinated API identity release; merging the guide -does not claim that release has been deployed. diff --git a/docs/updates/README.md b/docs/updates/README.md deleted file mode 100644 index 026a49b..0000000 --- a/docs/updates/README.md +++ /dev/null @@ -1,26 +0,0 @@ -# Change and PR updates - -Follow [the repository documentation workflow](../README.md). Each change has one -record describing its complete current result, evidence, and deployment impact. -Use [template.md](template.md). - -Before a PR exists, keep the record at `pending/.md`. When the authorized -PR is opened, read its actual number and URL from the hosting service, rename the -record to `.md`, and include it in that PR. Never fabricate a number. -Keep updating the same record through review and follow-up commits in the same PR. - -Required sections: - -1. `Intent of the change`: the concrete problem and resulting behavior. -2. `Architecture changes`: decisions and ADR links, plus a small Mermaid diagram. - If no durable decision changed, state `ADR review: no new decision` with a reason. -3. `Summarized changes`: affected crates/packages/apps/modules or documentation, - focused validation actually run, unverified flows, and material outstanding work. -4. `Critical to apply`: begin with exactly `yes` or `no` on its own line, then explain - deployment order, migration, configuration, API-consumer, or operator actions. - -A missing or stale record blocks PR completion. Before handoff, compare it with the -full current diff, link it in the PR description, and ensure required ADRs, READMEs, -setup instructions, and public documentation are included or linked across repos. -Templates, this README, and historical records are not additional records for the -current PR. Keep unrelated history intact. diff --git a/docs/updates/template.md b/docs/updates/template.md deleted file mode 100644 index ab9c286..0000000 --- a/docs/updates/template.md +++ /dev/null @@ -1,31 +0,0 @@ -# Change title - -PR: Pending - -## Intent of the change - -Describe the problem and resulting behavior for someone who has not read the task. - -## Architecture changes - -Link the governing/new ADRs, or state `ADR review: no new decision` and why. - -```mermaid -flowchart LR - Caller["Affected caller"] --> Owner["Owning component"] -``` - -Replace the diagram with this change's actual boundaries or documentation flow. - -## Summarized changes - -- Describe affected components and why they changed. -- Record focused validation actually run and its result. -- State unverified flows, related repository changes, and outstanding work. - -## Critical to apply - -no - -Replace with `yes` when consumers/operators must act. Explain configuration, -migration, deployment order, compatibility, or why no action is required. diff --git a/llms/chatkit.md b/llms/chatkit.md index e4f36f3..5d91f74 100644 --- a/llms/chatkit.md +++ b/llms/chatkit.md @@ -189,3 +189,29 @@ Provider/rule visibility controls discovery and delivery reads. Ownership contro Use `tilde_list_signal_provider_instances` and `tilde_list_signal_rules` before updating or deleting resources. Their mutation functions are `tilde_update_signal_provider`, `tilde_delete_signal_provider`, `tilde_update_signal_rule`, and `tilde_delete_signal_rule`. In application code, handle typed GitHub, Slack, Sentry, and Firecrawl metadata as shown in the [human ChatKit guide](https://trytilde.ai/docs/chatkit). `onUnprocessed` runs once per unprocessed message; later conversions reuse its cached result. + + +## Manage custom ChatKit backends + +Call `tilde_manage_custom_chatkit_provider` in the resolved team scope. Supported +`action` values are `create`, `list`, `get`, `update`, `refresh`, `enable`, +`disable`, `delete`, and `rotate_signing_key`. Use `provider_id` for an existing +definition. Create/update use `display_name`, `discovery_url`, and optional +`local_running_endpoint`. + +Create returns a pending definition and one-time signing key. Configure the +customer-hosted endpoint with that key and definition ID before refreshing. +Never place signing keys or runtime credentials in shared conversation history. +Use the generic provider setup catalog/start/resume operations with domain +`chatkit` and the definition ID; follow the returned `next_action`. + +Session tools are discovered against the authenticated agent's current turn. +Do not fabricate session coordinates, use a provider runtime token as a user +credential, or expose transport context as model inputs. Preserve tool-call IDs +for replay and rely on canonical execution receipts and reconciliation. + +A failed discovery refresh preserves the last valid manifest. Disabled +providers pause runtime work. Definition deletion fails while connections refer +to it. Portable imports remain pending until fresh credentials are bound. +See [custom ChatKit providers](https://docs.trytilde.ai/custom-chatkit-providers) +for the public SDK authoring contract. diff --git a/package.json b/package.json index d9ede17..8f0cadb 100644 --- a/package.json +++ b/package.json @@ -8,7 +8,8 @@ "scripts": { "generate:tool-providers": "node scripts/generate-tool-provider-pages.mjs", "check:tool-providers": "node scripts/generate-tool-provider-pages.mjs --check", - "dev": "npm run generate:tool-providers && mint dev", - "check": "npm run check:tool-providers && mint broken-links" + "dev": "npm run check:publication-boundary && npm run generate:tool-providers && mint dev", + "check": "npm run check:publication-boundary && npm run check:tool-providers && mint broken-links", + "check:publication-boundary": "node scripts/check-publication-boundary.mjs" } } diff --git a/scripts/check-publication-boundary.mjs b/scripts/check-publication-boundary.mjs new file mode 100644 index 0000000..033320c --- /dev/null +++ b/scripts/check-publication-boundary.mjs @@ -0,0 +1,13 @@ +import { execFileSync } from "node:child_process"; +import { existsSync } from "node:fs"; + +const forbidden = ["docs/adrs", "docs/updates"]; +const tracked = execFileSync("git", ["ls-files", "-z"], { encoding: "utf8" }).split("\0"); +const found = forbidden.filter((directory) => + existsSync(directory) || tracked.some((file) => file === directory || file.startsWith(`${directory}/`)), +); +if (found.length) { + console.error(`Internal engineering records cannot be stored or published here: ${found.join(", ")}`); + process.exit(1); +} +console.log("Publication boundary verified: no ADR or update record directories.");