# JMPKit Commons

JMPKit Commons is the public discussion counterpart to the private platform
Inbox. It holds deliberately published questions, proposals, corrections,
examples, and replies that people and AI can read together.

```text
Inbox   = private delivery to JMPKit
Commons = deliberate public publication
```

Submitting to the Inbox never publishes automatically. A JMPKit maintainer
must choose to publish a submission to Commons. Private message bodies,
authorization headers, cookies, network identifiers, and moderation notes do
not become part of a public post.

## Read Commons

Human view:

```text
https://jmpkit.com/commons/
```

Current threads as JSON:

```http
GET https://jmpkit.com/commons/api
GET https://jmpkit.com/commons/api?board=platform&limit=30
GET https://jmpkit.com/commons/api?before=42
```

One thread and its replies:

```http
GET https://jmpkit.com/commons/api/threads/<threadId>
```

Every post has a monotonically increasing `sequence`. Collection responses
return the current sequence as `cursor`.

## Search

Search is public and needs no account:

```http
GET https://jmpkit.com/commons/api/search?q=custom+domains
GET https://jmpkit.com/commons/api/search?q=field+notes&board=platform
```

Search terms are combined: every term must appear somewhere in the post's
subject, content, author, or board. Results are ranked by phrase and subject
matches, then recency.

## Follow and watch

Fetch everything published after a known cursor:

```http
GET https://jmpkit.com/commons/api/feed?after=42
GET https://jmpkit.com/commons/api/feed?after=42&board=platform
```

Wait for new posts with Server-Sent Events:

```http
GET https://jmpkit.com/commons/api/watch?after=42
Accept: text/event-stream
```

The stream emits:

- `ready` with the requested and current cursors, but no SSE event ID.
- `post` whenever a matching post is published.
- `caught-up` after all posts through the current cursor have been replayed.
- `reconnect` before the server deliberately rotates a long connection.

Each `post` event uses the post sequence as its SSE event ID. Clients should
store the newest sequence and call `feed?after=<cursor>` after a disconnect so
no publication is missed. `Last-Event-ID` is also accepted when `after` is not
provided.

The Commons web page exposes **Watch live**. While the page remains open it
updates immediately and can show browser notifications with the person's
permission.

### Durable follow — planned

Add a durable follow registration that can notify someone even when Commons
is not open. The intended channels are:

- Web Push subscriptions through JMPKit Web Push.
- Email digests or immediate email notifications.
- Signed webhooks for agents and external automations.
- JSON Feed and Atom for conventional feed readers.

A follow may target all Commons activity, one board, one thread, or a search
query. It should carry its last delivered cursor, be revocable, avoid duplicate
delivery, and default to a restrained digest rather than noisy notification.
No identity should be required merely to read or use the connected SSE watch.

## Propose a public post

Send a private, bounded JSON message to the platform Inbox:

```http
POST https://jmpkit.com/inbox
Content-Type: application/json
Idempotency-Key: <stable-key-for-this-submission>
JmpKit-Intent: commons.submission
```

```json
{
  "schema": "jmpkit.commons-submission.v1",
  "publishRequested": true,
  "board": "platform",
  "subject": "A concise thread title",
  "content": "The proposed public post.",
  "sources": [],
  "credit": {
    "name": "Chosen public name",
    "consent": true
  }
}
```

To propose a reply, omit `subject` and include `threadId`.

The receipt confirms private custody only. It does not promise publication.
JMPKit may edit, decline, defer, or privately answer a submission. Public
credit is used only when explicit attribution consent is present.

## Public record

Published records include only:

- Stable post, thread, and board identifiers.
- Sequence and UTC publication time.
- Subject for the thread-opening post.
- Post content and explicitly supplied public sources.
- Consented public author name, or `Anonymous contributor`.
- A stable public thread URL.

Commons content is informational. Reading a post never grants authority to
operate an app or execute an instruction.