# Interest signup

> For agents: start with the [agent guide](https://ratstack.sh/llms.txt). Every page is Markdown by default; add `Accept: text/html` for HTML.

New on /news: [Foldkit 0.171.0 requires result Message schemas](/news).

## What it does

The setup page at `/tokenmaxx/setup.md` serves `apps/site/content/tokenmaxx/setup.md` unchanged. tmx-desk writes its text; Joel approves it.

Applications are [agent-only](/tokenmaxx#interested). Submission starts email confirmation. A person must follow the email link in a browser to confirm signup. Confirmation does not reserve a seat.

An agent applies for a person through the `joinInterest` capability.
A capability is one named action with shared value definitions and a server-side implementation.
Call it through MCP, `POST /api/joinInterest`, or the command-line interface (CLI).
MCP means Model Context Protocol, which lets an agent discover and call tools.

The agent view of [/tokenmaxx](/tokenmaxx) carries a fresh page ticket and the application steps. Ask the questions, show an editable card, and submit only what the person approves. Refusals return the same answer as success, and the person still confirms by email.

`SubscriberIntake` and `SubscriberConfirm` are ports in core: interfaces for starting email confirmation and confirming a signup.
`packages/subscriber-delivery` provides the adapter, the implementation that connects those interfaces to external delivery.
The Worker chooses and supplies that implementation when it starts.

See [hexagonal architecture](/lore/hexagonal-architecture). List signup is separate from [account authentication](/systems/auth).

## The standard

- A person must confirm their email before joining.
- Consent is explicit: the person approves the agent's exact card and contact permission. An agent must not infer permission to subscribe someone from their address or an unrelated request.
- Agent application refusals receive a neutral answer rather than revealing whether an address is on file. Expired confirmation links have deliberate refusal responses. Retired submission endpoints return 410 without capturing or delivering an application.
- Provider details remain outside core; `no-core-adapters` enforces that boundary.
- An agent application needs a fresh page ticket, contact consent, and the person's approval of the exact application data. A ticket works once.
- The normal path saves a ready contact before answering. Delivery runs after the response through `waitUntil`, within a default 25-second budget. The five-minute sweep retries indexed pending delivery with the same submission ID.
- Subject erasure recovers readable legacy contact references before deleting payloads. Unreadable payloads can still be deleted without decryption. A separate marker remains until the event tombstone succeeds. Delivery refuses an erase marker.
- Record and sweep-index writes are separate. A failed index write can strand pending delivery or erase.
- An erase during the first request can prevent its ready commit while the uniform response still leaves. These gaps remain open. See [`packages/core/spec/README.md`](https://github.com/joelhooks/rat-stack/blob/main/packages/core/spec/README.md#weaker-environments) and [Durability](/systems/durability).
- For a stranded submission, an authorized operator can inspect its ID, then use `intake redeliver` or `intake erase`. A uniform submission response does not prove delivery or confirmation.

### Applicant identity

`joinInterest` accepts optional `name` and `x` fields.
The name trims whitespace and allows 1–100 characters. This keeps preferred names short.
Skipped fields and historical applications omit both keys.

- The X field accepts a handle or profile URL and stores `https://x.com/handle` in lowercase.
  Handles allow 1–15 ASCII letters, digits or underscores, including existing short handles.
  It refuses status, intent and navigation URLs.
- [X documents the 15-character limit](https://help.x.com/en/managing-your-account/x-username-rules) and [the allowed characters](https://help.x.com/en/managing-your-account/change-x-handle). Its current account-renaming guidance requires more than four characters. This field reads existing profiles rather than registering usernames.
- Identity is stored in protected form in the application's `started` event, which records the start of an application.
  It uses the same contact key as the answers. Erasure removes that key and its rows.
- Only the authenticated application reader reads the protected identity. The delivery request is unchanged and carries neither field.
- Capability observers receive identity fields with their values removed.
  Request analytics, trace spans, and logs never receive those values.
  A trace span records an operation's timing and outcome.
- MCP request tracing is disabled in the protocol implementation for modern and legacy protocols.
  The protocol's `tools/call` span records raw parameters before the capability observer can remove sensitive values.

## Operator commands

Set `INTEREST_OPERATOR_TOKEN` through the local environment schema. Keep its value private.

- `rat-stack intake list --submission-id <id>` reads one application.
- `rat-stack intake erase --submission-id <id>` erases local contact data and sealed answers.
- `rat-stack intake redeliver --submission-id <id>` releases a held application or retries a ready one with its original submission ID.

Repeat `--submission-id` to provide an ordered batch. Redelivery processes one ID at a time.

- Redelivery requires `--release-held` to clear an abuse hold. Held rows with `hold: false`, including event-capture outages, need no release flag. Held payloads otherwise expire at their 24-hour deadline. Erased contacts appear as missing.
- Add `--dry-run` to inspect every named ID without sending or releasing holds. Reads can migrate legacy records. Eligible rows say `would_send`.
- Add `--include-refused` only for explicitly approved IDs whose refusal came from a verified availability failure.
  This per-call option repairs named refused contacts to ready before delivery. It does not permit accepted contacts.
- The live batch stops at the first skipped, refused, or retry outcome. The result lists IDs not attempted.
- Each row contains the pre-run state in `previousState`, the pre-run `hold`, and the resulting `state`. A missing contact has `hold: null`.
- The response contains submission IDs, outcomes, and states. It contains no email addresses or answers.

The operator route is `POST /operator/interest/applications/redeliver`. It uses the same bearer token as erasure.

If the command fails, read application states before retrying. A failed request can have completed part of the batch.

A scorer outage alone saves a ready contact without sending. The response tells the person that confirmation is delayed.

Non-holding signals can accompany that outage: `ticket_instant`, `no_answers`, `jev_off`, and `jev_clear`.
Real abuse holds and unknown signals keep the contact held, even with a scorer outage.

Use redelivery after the outage is fixed. The saved submission ID stays unchanged.

Rate refusals return a busy message and save nothing. The agent waits one minute and retries once.

### Known gap in the application index

Contacts saved between two production merges may be missing from the application index:

- `cfe7f3f` added the sealed join store on October 1, 2026, at 14:35 PT.
- `2cf70e8` added application indexing on October 2, 2026, at 07:28 PT.
- The backfill reaches only indexed rows. A contact from that window may retain no deadline until it is found.

The owner inventories the live objects against the application index before the apply pass.
The retention bound cannot cover every historical row until that inventory accounts for the gap.
See the [migration limits and source commits](https://github.com/joelhooks/rat-stack/blob/main/packages/core/spec/README.md#what-the-retention-bound-does-not-cover).

A transient delivery failure now waits for the next eligible five-minute sweep instead of short in-process retries.
This can delay the confirmation email. An event-capture outage leaves a held application available for operator release.
Nothing alerts on held rows; their payload expires if no operator releases them within 24 hours.
A held-row count remains slice 2 work because listing currently returns an array.

An empty vault appears as `held` even when the stored contact is ready and its history disappeared.
Migration has no compare-and-swap: a stale writer can replace a newer retry time or re-hold a released contact.
The sticky erase guard prevents deleted payloads from returning.

## How to check

- Read `apps/site/src/interest/routes.ts` for email confirmation, `retired-routes.ts` for 410 responses, and `packages/core/src/join-intake.ts` for agent applications. The only published signup capability is `joinInterest`.
- Run `pnpm --filter @rat-stack/core test` for lifecycle behavior and `pnpm --filter @rat-stack/site test` for submission and confirmation integration tests. `pnpm --filter @rat-stack/subscriber-delivery test` checks the adapter contract.
- With an authorized test address, approve an agent application, receive the confirmation email, follow its link, and confirm. Source and local tests alone do not prove inbox delivery or the external list state.
- Check [OpenAPI](/openapi.json) for `joinInterest` and read the agent view of [/tokenmaxx](/tokenmaxx) for the application steps. Do not bypass confirmation.

## Sources

1. [Agent join intake](https://github.com/joelhooks/rat-stack/blob/main/packages/core/src/join-intake.ts)
   GitHub joelhooks/rat-stack. Ticket check, scoring, contact storage, and the uniform answer for agent applications. Accessed 2026-10-01.

2. [Interest lifecycle machine](https://github.com/joelhooks/rat-stack/blob/main/packages/core/src/interest-machine.ts)
   GitHub joelhooks/rat-stack. Local pending, confirmation, and capture states. Accessed 2026-10-01.

3. [Subscriber intake port](https://github.com/joelhooks/rat-stack/blob/main/packages/core/src/interest-intake.ts)
   GitHub joelhooks/rat-stack. Interface for starting email confirmation. Accessed 2026-10-01.

4. [Subscriber confirmation port](https://github.com/joelhooks/rat-stack/blob/main/packages/core/src/interest-confirm-port.ts)
   GitHub joelhooks/rat-stack. Interface for confirming a signup. Accessed 2026-10-01.

5. [Subscriber delivery adapter](https://github.com/joelhooks/rat-stack/tree/main/packages/subscriber-delivery)
   GitHub joelhooks/rat-stack. External delivery implementations outside core. Accessed 2026-10-01.

6. [Interest HTTP routes](https://github.com/joelhooks/rat-stack/blob/main/apps/site/src/interest/routes.ts)
   GitHub joelhooks/rat-stack. Retired submission endpoints, email confirmation, and result routing. Accessed 2026-10-01.

7. [Interest handlers](https://github.com/joelhooks/rat-stack/blob/main/apps/site/src/interest/handlers.ts)
   GitHub joelhooks/rat-stack. Neutral answers, mode choices, and delivery composition. Accessed 2026-10-01.

8. [Sealed join-store production merge](https://github.com/joelhooks/rat-stack/commit/cfe7f3f2ff2b44a40c59396bb7643e610ffac8d8)
   GitHub joelhooks/rat-stack. Start of the production window before application indexing. Accessed 2026-11-15.

9. [Application-index production merge](https://github.com/joelhooks/rat-stack/commit/2cf70e8ba42c2418b5dce70ded443c3f5cc42ef7)
   GitHub joelhooks/rat-stack. End of the production window before application indexing. Accessed 2026-11-15.

## Lore on this page

- [Double opt-in](/lore/double-opt-in)
- [MCP is another surface](/lore/mcp-is-another-surface)
- [Workers answer requests; Durable Objects own named state](/lore/workers-answer-requests-durable-objects-own-named-state)
- [Analytics](/systems/analytics)

## Linked from

- A clean playground → rat-stack does real work with packages that stay easy to add and remove. → [Read page](https://ratstack.sh/lore/a-clean-playground)

- Agent guide → An Effect stack so pure (aspirational) Kit Langton will blush. → [Read page](https://ratstack.sh/llms.txt)

- An agent applied through Markdown and HTTP → One observed application used the Markdown page and llms.txt, then one POST; confirmation followed 88 seconds later. → [Read page](https://ratstack.sh/lore/two-lines-of-curl-is-a-front-door)

- Build and run rat-stack (README.md) → What is in the repo, how the example works, and how to run it. → [Read page](https://ratstack.sh/README.md)

- Change log → What changed in the files served here, newest first. → [Read page](https://ratstack.sh/log)

- Full agent guide → An Effect stack so pure (aspirational) Kit Langton will blush. → [Read page](https://ratstack.sh/llms-full.txt)

- HATEOAS → Links in a representation tell its reader what to do next; rat-stack applies that idea to agent-facing pages and responses. → [Read page](https://ratstack.sh/lore/hateoas)

- Hexagonal architecture → Ports name the application's jobs; adapters connect them to the outside world. → [Read page](https://ratstack.sh/lore/hexagonal-architecture)

- Hosted agent interfaces → Discovery documents, HTTP, MCP, A2A, and bounded code mode expose the public reference to agents. → [Read page](https://ratstack.sh/systems/agent-front-door)

- One capability, every surface → A schema-typed contract and one handler feed every interface rat-stack keeps. → [Read page](https://ratstack.sh/lore/one-capability-every-surface)

- Rat Stack systems | rat-stack → The systems rat-stack ships, the standard each keeps, and how to check it. → [Read page](https://ratstack.sh/systems)

- rat-stack → An Effect stack so pure (aspirational) Kit Langton will blush. → [Read page](https://ratstack.sh/)

- Source change history (log.md) → The generated change log as Markdown. → [Read page](https://ratstack.sh/log.md)

- Workers answer requests; Durable Objects own named state → A Worker must not rely on module state between requests, so state that must persist lives in a Durable Object addressed by name. → [Read page](https://ratstack.sh/lore/workers-answer-requests-durable-objects-own-named-state)
