# First Chat Demo

The First Chat demo is the smallest runnable multi-process service demo in
capOS. It boots a resident `chat-server`, a bounded `chat-bot` actor, and a
native shell that can launch `chat-client` with explicit `StdIO` plus the
broker-issued operator `Chat` endpoint grant.

The chat service is not a shell builtin. The shell only launches a client
process and services that client's `StdIO` endpoint while the client talks to
the resident `Chat` endpoint. The focused manifest routes the kernel singleton
`chat_endpoint` through init to `chat-server`, which is the same endpoint the
broker facets into operator shell bundles.

## Run It

Use the focused QEMU proof:

```bash
make run-chat
```

The scripted proof creates a volatile shell credential, rejects an attempted
client endpoint relabel, launches `chat-client` under the authenticated shell
session, sends one lobby message, checks membership with `/who`, observes the
resident bot reply, quits the client, and exits the shell. The terminal
transcript should include:

```text
[chat] /join <channel>, /leave, /who, /exit, or plain text
[chat:#lobby]> hello from shell
[chat] #lobby <member-2> hello from shell
[chat] #lobby <member-1> [chat-bot] echo-bot heard you.
```

For default manual use, boot the ordinary playground:

```bash
make run
```

After login:

```text
run "chat-client" with { stdio: client @stdio, chat: client @chat }
```

The default playground starts the resident `chat-server` and includes
`chat-client`, but it does not start the bounded `chat-bot` proof actor. Use
`make run-chat` when you need the one-shot echo-bot transcript.

For lower-level manual proof work, let `make run-chat` build the focused ISO,
then boot `capos-chat.iso` yourself with the terminal UART attached to stdio and
the console UART written to a log.

Useful client commands:

```text
/join #other
/who
/leave
/exit
plain chat text
```

The resident bot is a bounded proof actor. If the operator waits too long
before joining and sending the first lobby message, the bot can time out and
exit; the chat client and server remain usable, but the bot reply will no
longer appear.

## What It Demonstrates

`make run-chat` and the manual terminal path described above currently show:

- `chat-server` runs as a resident service exporting only the `Chat` endpoint;
- `chat-server` keys membership by the opaque caller-session reference in the
  endpoint metadata, not by a caller-selected endpoint badge;
- `chat-bot` is a separate participant with a delegated chat client endpoint
  and its own session-bound membership record;
- `capos-shell` launches `chat-client` as an ordinary userspace process;
- the foreground client receives only explicit `StdIO` and `Chat` grants;
- caller-selected endpoint relabeling is rejected for delegated chat clients;
- the `handle` supplied to `join` is request data only; the service assigns
  visible `member-N` labels and the handle does not select membership
  authority or sender identity;
- lobby messages and bot replies are visible through the terminal transcript;
- `/who` lists current channel members from the resident service;
- client exit returns to the shell prompt, and the manifest child wait path
  observes clean shell and bot exits during normal completion.

## Current Limits

This is not yet a distinct-local-user chat surface over Telnet or multiple
terminals.

`system.cue` and `system-chat.cue` each boot one terminal-backed shell on the
QEMU terminal UART, and the shell's `run` command waits on the foreground
client's `StdIO` endpoint. Multiple `chat-client` runs can reuse the resident
service, but the current manual flow is one foreground client at a time. The
demo client still sends the hard-coded join handle `shell` for compatibility;
the server ignores it for visible sender labels and does not request disclosed
display/profile metadata from the session broker yet.

The default `make run` Telnet path now receives its shell bundle from
`AuthorityBroker`, including a profile-scoped `chat` endpoint for operator
shells. Guest and anonymous shells do not receive `chat` by default. A
Telnet-launched operator shell can therefore run the same `chat-client` command
after login. This is still not a distinct durable user chat surface: the demo
client joins with the hard-coded handle `shell`, the server assigns its own
visible member label, and multiple terminal sessions still need a
multi-session terminal host or network gateway before they are a real
multi-user chat model.

To make distinct local users chat through Telnet or terminals, capOS still
needs a multi-session terminal host or Telnet gateway that can keep multiple
shell sessions alive, grant each session a broker-authorized chat root/facet,
and disclose only the bounded display/profile metadata the user or broker
explicitly permits.