# Folkways Control Tower

> The dashboard for Folkways hosted real-time infrastructure. A workspace holds segments, one per real-time app and environment; each segment has signing keys, publishable keys and topic rules. This file tells AI agents how to read and operate it.

Signed-in pages use the person's session. There are three ways for an agent to help:

1. Scripts and back ends: call the Control Tower API with an API key (read-only). See "Control Tower API".
2. In the person's browser: use the agent tools on every signed-in page (WebMCP, or window.folkways.agent). See "Agent tools".
3. In a chat: the person presses "Copy for AI" in the top bar and pastes the page as Markdown or JSON.

Nothing an agent does creates, changes or deletes anything by itself: tools read and navigate, and forms are submitted by the person. Deleting a segment or workspace, revoking keys and removing members always ask the person to confirm.

## Concepts

- Workspace: an organisation with members, roles, a package (plan) and billing. URLs use its id.
- Segment: one real-time app, isolated from the rest. Use one per app and environment (production, staging, development).
- Signing keys: public keys (EdDSA or ES256; HS256 on the free plan) your back end signs short-lived client tokens with. A segment with none accepts no signed tokens.
- Publishable keys: read-only keys (rte_pk_…) for public pages; they need anonymous connections allowed in the segment's settings.
- Topic rules: patterns such as chat/> with a delivery class (durable, last_value, ephemeral), allowed operations (subscribe, publish, history, presence, signal) and limits. A segment with no rules denies every topic.
- API keys: fk_… keys for calling this API from servers, scoped to one workspace with per-entity permissions.
- Roles: owners and admins manage segments, keys and the team; owners also billing and deletion. Editors and viewers have view-only access: pages show a "View only" marker, forms for owners and admins don't open for them, and `folkways_get_page` reports `workspace.access: "view-only"` with the owners and admins to ask.

## Pages

Paths are relative to this dashboard. Every page is reachable by URL.

- `/w/{workspaceId}` Overview: Setup progress, live usage and the workspace at a glance.
- `/w/{workspaceId}/segments` Segments: Your real-time apps: signing keys, publishable keys, topic rules and connect guide.
- `/w/{workspaceId}/api-keys` API keys: Keys your servers use to call the Control Tower API (X-API-Key, read-only).
- `/w/{workspaceId}/analytics` Analytics: Connections, messages and data over time, per segment.
- `/w/{workspaceId}/team` Team: Members, roles and invitations. Owners and admins.
- `/w/{workspaceId}/billing` Billing: Package, usage this period and checkout. Owners and admins.
- `/w/{workspaceId}/settings` Settings: Rename or delete the workspace.
- `/` Workspaces: Every workspace you belong to; create a new one.
- `/me` Profile: Your name, password and account.
- `/w/{workspaceId}/segments/{segmentId}?tab={settings|keys|publishable|rules|connect}` One segment. Tabs: settings (Settings), keys (Signing keys), publishable (Publishable keys), rules (Topic rules), connect (Connect). Without ?tab it opens settings.

## Forms that open from a URL

Open one, fill in the visible fields, and ask the person to submit.

- `/?new` Create a workspace
- `/w/{workspaceId}/segments?new` Create a segment (owners and admins)
- `/w/{workspaceId}/api-keys?new` Create an API key (owners and admins)
- `/w/{workspaceId}/team?invite` Invite a team member (owners and admins)

## Agent tools

Every signed-in page registers these tools with the browser through WebMCP (navigator.modelContext) where the browser supports it, and always exposes them on `window.folkways.agent`:

- `window.folkways.agent.page()`: the open page as JSON (also in `<script type="application/json" id="folkways-agent-context">`).
- `window.folkways.agent.markdown()`: the same as Markdown.
- `await window.folkways.agent.call(name, input)`: run a tool. `window.folkways.agent.tools` lists them with JSON Schemas.

- `folkways_get_page`: Describe the Folkways dashboard page that is open: where you are (workspace, segment, tab), what it shows, your role, the forms you can open and the API calls that return the same data.
- `folkways_list_workspaces`: List the workspaces the signed-in person belongs to, with their plan, role and size.
- `folkways_list_segments`: List a workspace's segments (one per real-time app and environment) with their environment, status, key and rule counts, transports and effective limits.
- `folkways_get_segment`: Get one segment's configuration: settings, limits, identity policy, topic rules and signing-key metadata (never key material).
- `folkways_get_usage`: Get connections, messages and data for a workspace or one segment over the last N hours (default 24), with the per-segment breakdown.
- `folkways_navigate`: Open a dashboard page. Sections: dashboard (Setup progress, live usage and the workspace at a glance); segments (Your real-time apps: signing keys, publishable keys, topic rules and connect guide); api-keys (Keys your servers use to call the Control Tower API (X-API-Key, read-only)); analytics (Connections, messages and data over time, per segment); team (Members, roles and invitations); billing (Package, usage this period and checkout); settings (Rename or delete the workspace); workspaces (Every workspace you belong to; create a new one); profile (Your name, password and account). For a segment, pass segmentId and optionally tab.
- `folkways_open_form`: Open a form for the person to review and submit: create-workspace (Create a workspace); create-segment (Create a segment); create-api-key (Create an API key); invite-member (Invite a team member). Nothing is created until the person submits it. Fill the visible fields, then ask the person to confirm.

Tools never return secrets: no private keys, HS256 secrets or full API keys. Those are shown once, to the person, when created.

Pages use landmarks and labelled controls: a "Workspace" navigation, a "Breadcrumb" with the current path, and one h1 per page. Press Ctrl+K or ⌘K for the command bar.

## Control Tower API

- Base URL: https://ct.folkways.io/api/v1
- Auth for scripts: header `X-API-Key: fk_<keyId>_<secret>`. Create one under API keys. Keys are read-only for now and limited to the entities they were granted.
- OpenAPI: https://ct.folkways.io/api-docs (JSON), https://ct.folkways.io/swagger-ui.html (browsable)
- Responses are wrapped: `{ "status": "SUCCESS" | "ERROR", "message", "data", "meta", "statusCode" }`; errors carry `errors: [{ code, message, field? }]`.
- Workspaces are called organizations in the API.

Reads that mirror the dashboard:

- `GET /organizations/{workspaceId}`: the workspace, its members, segments and subscription
- `GET /organizations/{workspaceId}/segments`: segments with counts and effective limits
- `GET /segments/{segmentId}`: one segment's settings, limits and identity policy
- `GET /segments/{segmentId}/topic-rules`: its topic rules
- `GET /segments/{segmentId}/keys`: its signing keys (public parts only)
- `GET /organizations/{workspaceId}/usage?from={ISO-8601}`: connections and traffic, with a time series and per-segment totals
- `GET /organizations/{workspaceId}/usage/period`: this billing period's usage against the package's allowances
- `GET /segments/{segmentId}/usage?from={ISO-8601}`: one segment's usage

```bash
curl -s -H "X-API-Key: $FOLKWAYS_API_KEY" https://ct.folkways.io/api/v1/organizations/$WORKSPACE_ID/segments
```

## Docs

- [Folkways docs for AI assistants](https://docs.folkways.io/llms.txt): every docs page as Markdown
- [Folkways overview for AI assistants](https://folkways.io/llms.txt): products, pricing and what's live
- [JavaScript SDK quick start](https://docs.folkways.io/docs/js-sdk/quick-start)