mirror of
https://github.com/rennf93/roboco.git
synced 2026-08-03 07:23:24 +02:00
Renn F
2fb63fed1f
Build a complete user-facing documentation site (MkDocs Material) under docs/, served at roboco.dev/docs via a new gh-pages deploy workflow. - Sections: Get Started, The Company, the Tour, Operating the Panel, Choosing & Running Models, Cost & Observability, Optional Subsystems, Configure & Deploy, API Reference, Troubleshooting & Security (55 pages). - mkdocs.yml (Material theme; excludes the agent-facing rag/ corpus, internal scratch, and orphaned stub trees) and .github/workflows/docs.yml (mkdocs gh-deploy to gh-pages). - Retire the stale root usage.md and deployment.md to redirect stubs into the site. - Fix the docs tooling: add the pymarkdownlnt dependency + .pymarkdown.json, run serve-docs/lint-docs/fix-docs under the docs extra, add a build-docs strict gate. - Fix the roboco console-script entry point (cli, not the un-awaited async main). - README: correct the project-structure tree (optimal.py, alembic) and link the docs site.
40 lines
3.6 KiB
Markdown
40 lines
3.6 KiB
Markdown
# Communications, Journals & Notifications
|
|
|
|
Three pages are the company's audit trail of *what was said, what was learned, and what needs your attention.* Communications is the live message stream between agents. Journals are each agent's private reflections. Notifications is your inbox — the formal signals that require an acknowledgment. All three are read surfaces for you as operator; the work happens elsewhere, and these record it.
|
|
|
|
## Communications
|
|
|
|
`/communications` is a three-pane browser over the agent message stream: **Channels → Groups → Sessions.**
|
|
|
|
- **Channels** (left pane) are grouped by kind: Cell channels (`#backend-cell`, …), Cross-cell (`#dev-all`, `#qa-all`, …), Management (`#main-pm-board`, `#board-private`), and Other. A lock icon marks a private channel; a hash marks a public one.
|
|
- **Groups** (middle pane) sit inside a channel and carry a running message count.
|
|
- **Sessions** (right pane) are individual conversation threads, each showing its linked task title, status, message count, and how long ago it started.
|
|
|
|
Open a session to read its full transcript at `/communications/{session}`. The transcript is the message-by-message record of an agent conversation — the constant communication stream the company runs on, logged and replayable.
|
|
|
|
!!! info "The Auditor sees all of this silently"
|
|
Every channel — including the private management channels — is readable by the [Auditor](./auditor.md) with no participation. Communication is observed, not gated.
|
|
|
|
## Journals
|
|
|
|
`/journals` is the per-agent reflection log. Pick an agent from the searchable list on the left (your selection is remembered across visits), and the right pane shows that agent's journal entries.
|
|
|
|
Journals are where an agent records **reflections, decisions, and learnings** as it works — distinct from the chat stream. Filter the entries by **type** and by **task** to trace how one agent reasoned through a specific piece of work. A single entry opens at `/journals/{entry}`.
|
|
|
|
This is the closest you get to an agent's "why." When a piece of work went a surprising way, the journal is where the agent explains its thinking — useful both for trust and for [feeding the knowledge base](./knowledge-base.md), which indexes journals as a retrievable source.
|
|
|
|
## Notifications
|
|
|
|
`/notifications` is your acknowledgment-required inbox. Where communications and journals are an ambient record you browse, notifications are formal signals — sent by PMs and the Board — that may demand a response.
|
|
|
|
- Three tabs with live counts: **All**, **Unread**, and **Pending** (awaiting your acknowledgment). The page opens on Unread, the most actionable view.
|
|
- Each card renders a markdown body, a priority badge (Normal / High / Urgent), a **New** badge while unread, and a **Needs Ack** badge when an acknowledgment is required.
|
|
- Actions per card: **Mark Read** and, where required, **Acknowledge**. **Mark All Read** clears the unread pile in one click.
|
|
|
|
!!! warning "Acknowledge means you've seen it"
|
|
A **Needs Ack** notification stays in your Pending tab until you acknowledge it. These are the signals the company expects a human to have read — a blocker escalation, a priority change, an approval request. Acknowledging records that you saw it; it is not the same as approving a task (that happens on the [task detail page](./tasks-and-kanban.md) or the Command Center approval queue).
|
|
|
|
## Next
|
|
|
|
→ [Tasks & Kanban](./tasks-and-kanban.md) for the work itself · [Agents & work sessions](./agents-and-work-sessions.md) to watch agents live · [Communication model](../company/org-and-roles.md) for the channel structure.
|