# Issho v0.4.0 - Table of Contents

> An open-source collaboration toolkit for Phoenix: rooms, presence, documents and agent participation, for apps where people and AI agents work together in real time.

## Pages

- [Issho](readme.md)
- [Architecture](architecture.md)
- [Agents](agents.md)
- [Building a component on Issho](components.md)
- [Shared state](state.md)
- [Comments](comments.md)
- [Streams](streams.md)
- [Changelog](changelog.md)

## Modules

- [Issho](Issho.md): Collaboration for Phoenix: one engine for people and agents working
together live, under every component on a page.
- [Issho.Components](Issho.Components.md): Issho's pieces of a page, in HEEx. Import them where your app imports
its own components (`html_helpers` in `MyAppWeb`), and use them as
yours, `<.people>` and `<.pointers>`
- [Issho.Event](Issho.Event.md): Something that happened in a room, for whoever acts on it: the app's
code, the room's components, agents (`Issho.Events`).
- [Issho.Events](Issho.Events.md): A room's events (`Issho.Event`), on every node: subscribe to act on what
happens in it (an admin page, a job, an agent waiting for someone), and
emit an app's or a component's own.
- [Issho.Join](Issho.Join.md): How a component joins Issho: the same `issho` option in every
component (Kotoba's editor, Hakushi's canvas, Masu's grid, yours), so an
app writes it once and it means the same everywhere.
- [Issho.Live.Comments](Issho.Live.Comments.md): The threads of comments of a room, on the page: a panel of the open
and resolved threads, each with its comments, replies, reactions, and
a composer, and a mark at each thread's place, drawn where its
component locates it. Render it with `Issho.Components.comments/1`, in
a LiveView that is in the room (`Issho.Live.join/4`).
- [Issho.MCP](Issho.MCP.md): Issho's tools over MCP, with [Sake](https://hex.pm/packages/sake): a
`Sake.Server` of the tools you give, Issho's (`Issho.Tools.room/0`)
and the components' (`Kotoba.Issho.tools/0`, `Hakushi.Issho.tools/0`),
for any MCP client. The same tools serve your app's own model without
MCP (`Issho.Tools`).
- [Issho.MCP.Session](Issho.MCP.Session.md): Who an MCP caller is in Issho's rooms: the `Issho.Tool.Context` its
tool calls run with. The one place where an MCP endpoint's
authorization (Sake's, your own, or none) meets Issho: the agent and
the options of its joins come from the call.
- [Issho.MCP.Setup](Issho.MCP.Setup.md): Issho's MCP settings for one endpoint, as a plug before it: which
instance, and who its callers are in the rooms. An app can serve its
tools on several endpoints, each with its own
- [Issho.Motion](Issho.Motion.md): How an agent moves on the page, so that the people can follow it: it
goes to where it works, presses, drags and lets go, and clicks, as a
hand would. Only where it goes is sent, once for each gesture; each
browser draws the way there on its own page, and the agent waits as long
as that takes before its change lands.
- [Issho.Tool](Issho.Tool.md): A tool an agent uses in Issho's rooms, however it reaches your app: an
MCP client (`Issho.MCP`), your app's own model through an API
(`Issho.Tools`), or whatever comes next. A tool says what it does and
what it takes, as a JSON Schema; it runs as the agent of an
`Issho.Tool.Context`, under your policy, as anyone in a room does.
- [Issho.Tool.Context](Issho.Tool.Context.md): Who runs a tool: the agent (an `Issho.Actor`), the options of its joins
(`:on_behalf_of`, `:claims`, `:can`), and the instance. A front end
makes it from its caller: `Issho.MCP` from an MCP call, your code from
the user your app's model works for.
- [Issho.Tools](Issho.Tools.md): Tools for agents, for any way an agent reaches your app. Issho's room
tools are `room/0`; the components bring theirs
(`Kotoba.Issho.tools/0`, `Hakushi.Issho.tools/0`), and you can write
your own (`Issho.Tool`).

- Contracts
  - [Issho.Actor](Issho.Actor.md): Anyone or anything that takes part in a room: a user, an admin, a guest,
a service, an agent. Issho never assumes your schema; implement this
protocol for each struct that can join.
  - [Issho.Binding](Issho.Binding.md): What a component brings to Issho: its engine (`Issho.Engine`) and its
place format (`Issho.Place`). The browser's half of a binding brings the
rest: drawing places, and reading and applying a view for following.
  - [Issho.Engine](Issho.Engine.md): The model of a document: how its operations apply. Each binding brings
one (Kotoba's text, Hakushi's graph, a map for shared assigns), and the
authority (`Issho.Authority`) runs it.
  - [Issho.Place](Issho.Place.md): Where someone is, in a component's own terms: a row and a column in a
grid, a node and an offset in a text, a point on a canvas. Never screen
pixels, because each person has their own order, filters and zoom.
  - [Issho.Policy](Issho.Policy.md): Your app's answer to "may this actor do this here?", and to "what is
this document?". Issho has no roles and no user model: it asks, and your
app answers with whatever it already uses.
  - [Issho.Store](Issho.Store.md): Where documents last. Your app implements it on its database;
`Issho.Store.Memory` is for development and tests.

- Documents
  - [Issho.Authority](Issho.Authority.md): The one process that orders a document's changes, across every node of
a cluster.
  - [Issho.Documents](Issho.Documents.md): The authorities (`Issho.Authority`) of an Issho instance: one for each
open document, found by name on every node of a cluster.
  - [Issho.Engine.Map](Issho.Engine.Map.md): A map that people and agents change together: values at paths, and
lists of items by their id, in the order the authority accepts them. It
is the engine of shared state (`Issho.State`), the reference for writing
an engine, and the engine of Issho's own tests.
  - [Issho.Transaction](Issho.Transaction.md): The envelope of a change to a document, the same for every engine

- Comments
  - [Issho.Comments](Issho.Comments.md): Threads of comments on the places of a room's components: a range of a
text, a node of a canvas, a cell of a grid, or the page as a whole.
People and agents start them, reply, edit and delete their own, react,
mention each other, resolve and reopen them.
  - [Issho.Comments.Ops](Issho.Comments.Ops.md): The operations of a room's comments document (`Issho.Engine.Comments`),
for a LiveView, an agent's participant, or your own code to commit
  - [Issho.Engine.Comments](Issho.Engine.Comments.md): The threads of comments of a room: the engine of its comments document
(`Issho.Comments`). Its browser twin is `commentsEngine`, held to the
same cases (`test/corpus/engine_comments.json`).
  - [Issho.Inbox](Issho.Inbox.md): What was said to someone while they were away: each comment that
mentions them, in any room, kept until they have read it. An agent
that was not in the room when a person wrote "@Claude, a look?" finds
it here when it next comes (the `inbox` tool), and the app can wake it
at once (`:on_mention`).

- Streams
  - [Issho.Stream](Issho.Stream.md): A stream of a room, as it is now (`Issho.Streams`): what it is, whom it
is for, who writes it, where it is, its state and what it holds so far.
  - [Issho.Streams](Issho.Streams.md): Streams of a room: output that a process writes a piece at a time (a
model's answer, an agent's report, an import's log), that people see as
it comes, and find again when they come back: from another page,
another tab, after their connection dropped, on another node.

- Rooms
  - [Issho.Awareness](Issho.Awareness.md): Where the people of a room are, and what they are doing: their places,
selections, drags and locks, many times a second.
  - [Issho.Channel](Issho.Channel.md): The channel a browser joins a room on: one per room per tab, on one
socket for the whole page.
  - [Issho.Color](Issho.Color.md): The colours of the people of a room.
  - [Issho.Identity](Issho.Identity.md): An actor as a room knows it: its key, what others see of it, and on
whose behalf it acts.
  - [Issho.Presence](Issho.Presence.md): Who is in a room: `Phoenix.Presence`, as it is, on your app's PubSub.
  - [Issho.Token](Issho.Token.md): Short-lived, signed credentials to join one room as one actor.

- LiveView
  - [Issho.Live](Issho.Live.md): A LiveView in a room: the same session as a browser's channel or an
agent's process, in the LiveView's own process. Presence, awareness,
the room's documents and the policy work the same; the room's events
reach the LiveView's components with `send_update/2`, or the LiveView
itself.
  - [Issho.State](Issho.State.md): Shared state without an engine of your own: a map that people and
agents change together (`Issho.Engine.Map`), as a LiveView assign that
stays up to date. A retro board, a poll, a checklist, a kanban's order,
a game's turn.

- Agents
  - [Issho.Agents](Issho.Agents.md): Agents in rooms for front ends without a lasting connection: an MCP
server, whose every tool call is its own request, a webhook, a chat
bot. An agent joins a room on its first call and stays, present and
where it last pointed, between calls; it leaves after `:idle`
milliseconds with no call (ten minutes), or when told.
  - [Issho.MCP.Inbox](Issho.MCP.Inbox.md): The caller's inbox as an MCP resource, `issho://inbox`: the comments
that mention it while it was away (`Issho.Inbox`), not yet read. A
client that subscribes hears when it changes. Reading it leaves them
unread: the `inbox` tool takes them.

  - [Issho.Participant](Issho.Participant.md): An actor in a room from Elixir: an agent running in your app, a job, a
script. It joins like a browser, with the same presence, awareness,
locks, transactions and policy, and the people in the room see it.
  - [Issho.Work](Issho.Work.md): What an agent is doing in a room, seen by the people in it, and their
hand on it: a task, its steps and how far it is, and Pause, Resume and
Stop.

- Stores
  - [Issho.Store.Memory](Issho.Store.Memory.md): A store in memory, for development and tests. It outlives a document's
authority, but loses everything when its node stops.
  - [Issho.Store.None](Issho.Store.None.md): No store: a document that lasts as long as its authority, and starts
again from its initial content when the next one opens it.

- Testing
  - [Issho.Test](Issho.Test.md): Helpers for testing an app or a binding with Issho, in ExUnit.

## Mix Tasks

- [mix issho.build](Mix.Tasks.Issho.Build.md): Builds Issho's browser client into `priv/static`.
- [mix issho.release_check](Mix.Tasks.Issho.ReleaseCheck.md): Checks the built files before a release of Issho.