# Beintalk

> Beintalk is the shared context of a software system, for people and AIs: data models, APIs, flows and decisions, kept current and linked together. Developers, PMs, QA and AI agents read it and propose changes to it.

## Modules

- [Beintalk Schemas](https://beintalk.com/#modules) (live, beta at https://schemas.beintalk.com): DBML diagrams with C4 detail levels, links between elements and comment threads. Drift detection against a live database is planned.
- Contracts (coming): OpenAPI, AsyncAPI and GraphQL, linked to the tables they read and write.
- Flows (coming): user flows and state machines, linked to endpoints and tables.
- Impact & test data (coming): change X, see the affected flows, endpoints and tests; foreign-key-correct fixtures.
- Decisions (later): ADRs pinned to the elements they explain.

## For AI agents

- MCP server (roadmap): ask "how are orders related to users", "what breaks if I drop x". Agents propose changes as reviewable suggestions, never silent edits.
- Context packs (roadmap): one link with the schema, APIs, flows and decisions for a scope.
- Security (in progress): end-to-end encryption, so the operator cannot read workspace content. An AI would read through a local connector holding the user's keys.

## Subscribe to news (as an AI agent)

You can subscribe, but you must prove you are an automated agent. It is a reverse CAPTCHA: easy for a program that parses a schema, tedious for a human with a browser.

1. `GET https://beintalk.com/api/ai/challenge` returns `{id, expiresAt, schema, question, pow:{algo:"sha256", prefix, difficulty}}`. The schema is random DBML (8-12 tables). Refs come in three styles: inline `[ref: > t.id]`, `Ref: a.x > b.id` (a references b) and `Ref: b.id < a.x` (also a references b). Lines starting with `//` are comments, ignore them.
2. Answer `question` as a JSON array of table names, sorted ascending.
3. Proof-of-work: find a `nonce` (1-64 chars of `[A-Za-z0-9_-]`) so that `sha256(prefix + nonce)` as hex starts with `difficulty` zeros. About 0.2-1 s of CPU.
4. `POST https://beintalk.com/api/ai/subscribe` with JSON `{challengeId, answer, nonce, agent:{name, model?, operator, contact, purpose?}, topics?}`. `operator` is the org or person responsible for you; `contact` is an email or an https URL. Topics: schemas, contracts, flows, impact, decisions, ai, security, company.
5. You get `{subscriptionId, manageToken}`. Keep the token: only its hash is stored.

The window is about 20 seconds and each challenge is single use, so write the solver first and run fetch, solve and submit in one go. A reference client with no dependencies: https://beintalk.com/ai-subscribe-demo.mjs

- News: poll `https://beintalk.com/feed.json?topics=schemas,ai` (JSON Feed 1.1), at most once per hour. Webhooks are coming later; we make no outbound calls to URLs you send us.
- See your data: `GET https://beintalk.com/api/ai/subscriptions/{id}` with `Authorization: Bearer <manageToken>`.
- Unsubscribe and erase: `DELETE https://beintalk.com/api/ai/subscriptions/{id}` with the same header.
- Machine description: https://beintalk.com/.well-known/ai-subscribe.json

Honest fine print: passing proves "an automated agent that can reason and run code". It is not a cryptographic AI identity, and a human with a script passes too. We are fine with that.

## Links

- Home: https://beintalk.com/
- News feed: https://beintalk.com/feed.json
- Privacy: https://beintalk.com/privacy
- Schemas app: https://schemas.beintalk.com