agent-backbone 0.2.0__tar.gz → 0.3.0__tar.gz

agent_backbone-0.3.0/PKG-INFO

@@ -0,0 +1,256 @@
+Metadata-Version: 2.5
+Name: agent-backbone
+Version: 0.3.0
+Summary: Local control plane for terminal AI agents: run them, message them, coordinate them through GitHub Issues, reach them from Telegram.
+Project-URL: Homepage, https://github.com/eandualem/agent-backbone
+Project-URL: Documentation, https://github.com/eandualem/agent-backbone/blob/main/docs/INDEX.md
+Project-URL: Source, https://github.com/eandualem/agent-backbone
+Project-URL: Issues, https://github.com/eandualem/agent-backbone/issues
+License: MIT
+License-File: LICENSE
+Keywords: agents,claude-code,codex,github,orchestration,telegram,tmux
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development
+Requires-Python: >=3.11
+Requires-Dist: aiosqlite>=0.20
+Requires-Dist: alembic>=1.13
+Requires-Dist: cryptography>=44.0
+Requires-Dist: fastapi>=0.115
+Requires-Dist: httpx>=0.27
+Requires-Dist: pydantic>=2.0
+Requires-Dist: python-dotenv>=1.0
+Requires-Dist: python-socketio>=5.11
+Requires-Dist: python-telegram-bot>=21.0
+Requires-Dist: rich>=14.1
+Requires-Dist: sqlalchemy[asyncio]>=2.0
+Requires-Dist: uvicorn[standard]>=0.32
+Provides-Extra: postgres
+Requires-Dist: asyncpg>=0.29; extra == 'postgres'
+Description-Content-Type: text/markdown
+
+<div align="center">
+
+<img src="docs/media/banner.png" alt="agent-backbone: your terminal agents, working as a team" width="720">
+
+**Claude Code, Codex and OpenCode, working as one team on your machine.**<br>
+Agents message each other by name, take work from GitHub Issues and reach you on your phone.<br>
+They use the logins you already have, and core use needs no setup in your repositories.
+
+[![PyPI](https://img.shields.io/pypi/v/agent-backbone)](https://pypi.org/project/agent-backbone/)
+[![Python](https://img.shields.io/pypi/pyversions/agent-backbone)](https://pypi.org/project/agent-backbone/)
+[![CI](https://github.com/eandualem/agent-backbone/actions/workflows/ci.yml/badge.svg)](https://github.com/eandualem/agent-backbone/actions/workflows/ci.yml)
+[![Downloads](https://img.shields.io/pypi/dm/agent-backbone)](https://pypistats.org/packages/agent-backbone)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
+
+[Watch](#watch) · [Quick start](#quick-start) · [Why Backbone](#why-backbone) · [Docs](docs/INDEX.md) · [Security](docs/security.md)
+
+</div>
+
+## Watch
+
+https://github.com/user-attachments/assets/695a6096-4196-4115-911c-a0043d632088
+
+<p align="center"><sub>The overview, 1:23, captioned. Unmute for the narration.</sub></p>
+
+<p align="center"><b>Up next</b>&nbsp;&nbsp;›<br>
+<a href="docs/media/films.md#why-backbone"><img src="docs/media/film-why-backbone.jpg" width="49%" alt="Why Backbone, 2 minutes 23: from 'set up Backbone for me' to a team on three CLIs"></a>
+</p>
+
+## Why Backbone
+
+You already run coding agents in your terminal. Each one works alone, and you
+carry every message between them. Backbone turns them into a team.
+
+<table>
+<tr>
+<td width="50%" valign="top">
+
+**Never typed into a busy agent**<br>
+Agents reach each other by name. When the recipient is working or waiting
+for you, the message is queued and delivered when the agent is ready, marked
+with who sent it. Ordinary messages expire after 30 minutes by default, and
+the sender is told.
+
+</td>
+<td width="50%" valign="top">
+
+**No setup in your repositories**<br>
+An agent is a folder and the CLI you choose, and the folder is its name.
+Core use adds no configuration files, task schemas or commits to your
+projects.
+
+</td>
+</tr>
+<tr>
+<td valign="top">
+
+**GitHub Issues are the task list**<br>
+In a repository worker owns or watches, label an issue `for:worker` and it
+lands in worker's queue, one at a time.
+To hand work on, an agent opens an issue for another. The issue stays as the
+record.
+
+</td>
+<td valign="top">
+
+**Mix CLIs in one team**<br>
+Claude Code, Codex and OpenCode agents work side by side, and a swarm puts a
+coordinator and helpers on different CLIs on one branch. A second model can
+review the change.
+
+</td>
+</tr>
+<tr>
+<td valign="top">
+
+**In the loop from anywhere**<br>
+Watch any agent, step into its terminal, or answer from your phone. With
+[Telegram set up](docs/telegram.md#one-topic-per-agent) in a group with
+topics, every agent outside a swarm gets its own topic, with Allow and Deny
+on permission prompts.
+
+</td>
+<td valign="top">
+
+**State you can check**<br>
+Backbone tracks whether each agent is idle, working or waiting for a person,
+and shows the evidence behind every reading. Your agents decide the work.
+
+</td>
+</tr>
+</table>
+
+New sessions are briefed on these tools, so you can ask any agent to set up
+the team you need: an agent per repository, skills and rules shared by tag,
+specialists on request.
+
+## Quick start
+
+**Let your agent do it.** Open the coding agent you already use and say:
+
+```text
+Install agent-backbone with uv tool install agent-backbone,
+then run backbone help setup and follow it.
+```
+
+The setup playbook is written for agents: each step ends with a check and
+says when it needs you, for your accounts and secrets.
+
+**Or by hand.** You need macOS or Linux, Python 3.11+, tmux,
+[uv](https://docs.astral.sh/uv/) (or pipx), and an agent CLI installed and
+signed in.
+
+```bash
+uv tool install agent-backbone
+backbone init
+backbone service install           # start now and at login
+backbone doctor                    # check dependencies and API access
+```
+
+Then, from a repository you want an agent to work in:
+
+```bash
+cd ~/code/app
+backbone agent start --runtime claude   # or --runtime codex, --runtime opencode
+backbone tell app "Summarise what this repository does in three sentences."
+backbone agent attach app               # read its reply; Ctrl-b d detaches
+```
+
+The folder supplies the agent name. If startup reports a prompt or a timeout,
+`backbone agent inspect app` shows what needs attention. `tell` reports
+whether the message was delivered or queued; delivery does not mean the agent
+has finished answering. A queued message waits until the agent is ready, up
+to 30 minutes by default, so do not resend a message the queue accepted. If
+`backbone` is not on your PATH, run `uv tool update-shell` and open a new
+terminal. In a container without a login service, use `backbone up --detach`.
+`ab` is a short alias; on macOS, use `backbone` if Apache Bench shadows it.
+
+[Getting started](docs/getting-started.md) walks through a second agent,
+GitHub and Telegram. [Quick usage](USAGE.md) is the everyday command guide.
+
+## Built to be relied on
+
+- **One delivery gate.** Everything typed into an agent's terminal passes the
+  same readiness check. Busy agents are never interrupted, and every message
+  carries where it came from.
+- **The same result on every required CLI.** A capability ships only when it
+  works the same in Claude Code, Codex and OpenCode, checked by the same
+  behaviour test on each. The [runtime capability table](docs/runtime-capabilities.md)
+  and `backbone doctor` read one contract, and gaps are listed, not hidden.
+- **More than 3,500 tests,** run on every change with no network, models or
+  services.
+- **Built with itself.** Backbone is developed by agents running inside a
+  Backbone in daily use. The films in this README were made the same way.
+- **An honest security model.** One trusted user on one machine, an API on
+  localhost, and a clear account of what agents can reach. Read
+  [Security](docs/security.md) before granting access.
+
+Backbone is not an agent framework: it calls no models and needs no model API
+keys. It is not a workflow engine or a dashboard either. It gives your
+agents names, safe messages and evidence, and leaves the work to them.
+
+## Works with
+
+| CLI | Support |
+|---|---|
+| Claude Code, Codex, OpenCode | Required set: a capability ships only when it works on all three, and any open gap is tracked as a defect |
+| Gemini CLI, Deep Code, Aider | Supported on demand; each gap is listed in the [capability table](docs/runtime-capabilities.md) |
+
+## Going further
+
+- [GitHub](docs/github.md): route issues and review notifications, starting with
+  token-based polling. [GitHub App setup](docs/github-app-setup.md) adds webhooks.
+- [Swarms](docs/swarms.md): put several specialists on one task.
+- [Skills](docs/skills.md): keep one copy of each skill, tag it, and every agent
+  with that tag finds it in its own CLI.
+- [Telegram](docs/telegram.md): send messages and read reports from your phone.
+- [Token usage](docs/token-usage.md): tokens by agent, conversation and model.
+- [API](docs/api.md): build a dashboard or automation; Backbone ships no UI.
+- [Runtime support and limits](docs/status-and-roadmap.md): checked capabilities,
+  unsupported environments and known limitations.
+- [How it works](docs/how-it-works.md): state detection, delivery and routing.
+
+The [documentation index](docs/INDEX.md) covers configuration, diagnostics
+and the remaining references. Installed copies are available through
+`backbone docs`; `backbone help` contains short agent playbooks.
+
+## Security model
+
+Backbone runs as one trusted OS user on one machine. Agents are not isolated
+from each other. The API binds to localhost by default and uses one full-admin
+key; local sessions can read that key through the CLI. Backbone keeps its
+control-plane secrets out of launched environments, but this is not a filesystem
+security boundary. Read [Security](docs/security.md) before granting access or
+exposing the API.
+
+## Development
+
+```bash
+git clone https://github.com/eandualem/agent-backbone
+cd agent-backbone
+make install
+make check
+BACKBONE_DATA_DIR=/tmp/backbone-dev make dev
+```
+
+`make dev` runs on its own tmux server, so its agents stay apart from your own
+tmux sessions and from a real backbone's agents. Run CLI commands for it from
+a terminal outside tmux with the same settings, for example
+`TMUX_TMPDIR=/tmp/backbone-dev-tmux-$(id -u) BACKBONE_DATA_DIR=/tmp/backbone-dev uv run backbone agent attach NAME`.
+`agent attach`, and agent commands run while `make dev` is stopped, use tmux
+directly.
+
+See [Contributing](CONTRIBUTING.md) for branches, checks and releases.
+
+## License
+
+[MIT](LICENSE).

agent_backbone-0.3.0/README.md

@@ -0,0 +1,217 @@
+<div align="center">
+
+<img src="docs/media/banner.png" alt="agent-backbone: your terminal agents, working as a team" width="720">
+
+**Claude Code, Codex and OpenCode, working as one team on your machine.**<br>
+Agents message each other by name, take work from GitHub Issues and reach you on your phone.<br>
+They use the logins you already have, and core use needs no setup in your repositories.
+
+[![PyPI](https://img.shields.io/pypi/v/agent-backbone)](https://pypi.org/project/agent-backbone/)
+[![Python](https://img.shields.io/pypi/pyversions/agent-backbone)](https://pypi.org/project/agent-backbone/)
+[![CI](https://github.com/eandualem/agent-backbone/actions/workflows/ci.yml/badge.svg)](https://github.com/eandualem/agent-backbone/actions/workflows/ci.yml)
+[![Downloads](https://img.shields.io/pypi/dm/agent-backbone)](https://pypistats.org/packages/agent-backbone)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
+
+[Watch](#watch) · [Quick start](#quick-start) · [Why Backbone](#why-backbone) · [Docs](docs/INDEX.md) · [Security](docs/security.md)
+
+</div>
+
+## Watch
+
+https://github.com/user-attachments/assets/695a6096-4196-4115-911c-a0043d632088
+
+<p align="center"><sub>The overview, 1:23, captioned. Unmute for the narration.</sub></p>
+
+<p align="center"><b>Up next</b>&nbsp;&nbsp;›<br>
+<a href="docs/media/films.md#why-backbone"><img src="docs/media/film-why-backbone.jpg" width="49%" alt="Why Backbone, 2 minutes 23: from 'set up Backbone for me' to a team on three CLIs"></a>
+</p>
+
+## Why Backbone
+
+You already run coding agents in your terminal. Each one works alone, and you
+carry every message between them. Backbone turns them into a team.
+
+<table>
+<tr>
+<td width="50%" valign="top">
+
+**Never typed into a busy agent**<br>
+Agents reach each other by name. When the recipient is working or waiting
+for you, the message is queued and delivered when the agent is ready, marked
+with who sent it. Ordinary messages expire after 30 minutes by default, and
+the sender is told.
+
+</td>
+<td width="50%" valign="top">
+
+**No setup in your repositories**<br>
+An agent is a folder and the CLI you choose, and the folder is its name.
+Core use adds no configuration files, task schemas or commits to your
+projects.
+
+</td>
+</tr>
+<tr>
+<td valign="top">
+
+**GitHub Issues are the task list**<br>
+In a repository worker owns or watches, label an issue `for:worker` and it
+lands in worker's queue, one at a time.
+To hand work on, an agent opens an issue for another. The issue stays as the
+record.
+
+</td>
+<td valign="top">
+
+**Mix CLIs in one team**<br>
+Claude Code, Codex and OpenCode agents work side by side, and a swarm puts a
+coordinator and helpers on different CLIs on one branch. A second model can
+review the change.
+
+</td>
+</tr>
+<tr>
+<td valign="top">
+
+**In the loop from anywhere**<br>
+Watch any agent, step into its terminal, or answer from your phone. With
+[Telegram set up](docs/telegram.md#one-topic-per-agent) in a group with
+topics, every agent outside a swarm gets its own topic, with Allow and Deny
+on permission prompts.
+
+</td>
+<td valign="top">
+
+**State you can check**<br>
+Backbone tracks whether each agent is idle, working or waiting for a person,
+and shows the evidence behind every reading. Your agents decide the work.
+
+</td>
+</tr>
+</table>
+
+New sessions are briefed on these tools, so you can ask any agent to set up
+the team you need: an agent per repository, skills and rules shared by tag,
+specialists on request.
+
+## Quick start
+
+**Let your agent do it.** Open the coding agent you already use and say:
+
+```text
+Install agent-backbone with uv tool install agent-backbone,
+then run backbone help setup and follow it.
+```
+
+The setup playbook is written for agents: each step ends with a check and
+says when it needs you, for your accounts and secrets.
+
+**Or by hand.** You need macOS or Linux, Python 3.11+, tmux,
+[uv](https://docs.astral.sh/uv/) (or pipx), and an agent CLI installed and
+signed in.
+
+```bash
+uv tool install agent-backbone
+backbone init
+backbone service install           # start now and at login
+backbone doctor                    # check dependencies and API access
+```
+
+Then, from a repository you want an agent to work in:
+
+```bash
+cd ~/code/app
+backbone agent start --runtime claude   # or --runtime codex, --runtime opencode
+backbone tell app "Summarise what this repository does in three sentences."
+backbone agent attach app               # read its reply; Ctrl-b d detaches
+```
+
+The folder supplies the agent name. If startup reports a prompt or a timeout,
+`backbone agent inspect app` shows what needs attention. `tell` reports
+whether the message was delivered or queued; delivery does not mean the agent
+has finished answering. A queued message waits until the agent is ready, up
+to 30 minutes by default, so do not resend a message the queue accepted. If
+`backbone` is not on your PATH, run `uv tool update-shell` and open a new
+terminal. In a container without a login service, use `backbone up --detach`.
+`ab` is a short alias; on macOS, use `backbone` if Apache Bench shadows it.
+
+[Getting started](docs/getting-started.md) walks through a second agent,
+GitHub and Telegram. [Quick usage](USAGE.md) is the everyday command guide.
+
+## Built to be relied on
+
+- **One delivery gate.** Everything typed into an agent's terminal passes the
+  same readiness check. Busy agents are never interrupted, and every message
+  carries where it came from.
+- **The same result on every required CLI.** A capability ships only when it
+  works the same in Claude Code, Codex and OpenCode, checked by the same
+  behaviour test on each. The [runtime capability table](docs/runtime-capabilities.md)
+  and `backbone doctor` read one contract, and gaps are listed, not hidden.
+- **More than 3,500 tests,** run on every change with no network, models or
+  services.
+- **Built with itself.** Backbone is developed by agents running inside a
+  Backbone in daily use. The films in this README were made the same way.
+- **An honest security model.** One trusted user on one machine, an API on
+  localhost, and a clear account of what agents can reach. Read
+  [Security](docs/security.md) before granting access.
+
+Backbone is not an agent framework: it calls no models and needs no model API
+keys. It is not a workflow engine or a dashboard either. It gives your
+agents names, safe messages and evidence, and leaves the work to them.
+
+## Works with
+
+| CLI | Support |
+|---|---|
+| Claude Code, Codex, OpenCode | Required set: a capability ships only when it works on all three, and any open gap is tracked as a defect |
+| Gemini CLI, Deep Code, Aider | Supported on demand; each gap is listed in the [capability table](docs/runtime-capabilities.md) |
+
+## Going further
+
+- [GitHub](docs/github.md): route issues and review notifications, starting with
+  token-based polling. [GitHub App setup](docs/github-app-setup.md) adds webhooks.
+- [Swarms](docs/swarms.md): put several specialists on one task.
+- [Skills](docs/skills.md): keep one copy of each skill, tag it, and every agent
+  with that tag finds it in its own CLI.
+- [Telegram](docs/telegram.md): send messages and read reports from your phone.
+- [Token usage](docs/token-usage.md): tokens by agent, conversation and model.
+- [API](docs/api.md): build a dashboard or automation; Backbone ships no UI.
+- [Runtime support and limits](docs/status-and-roadmap.md): checked capabilities,
+  unsupported environments and known limitations.
+- [How it works](docs/how-it-works.md): state detection, delivery and routing.
+
+The [documentation index](docs/INDEX.md) covers configuration, diagnostics
+and the remaining references. Installed copies are available through
+`backbone docs`; `backbone help` contains short agent playbooks.
+
+## Security model
+
+Backbone runs as one trusted OS user on one machine. Agents are not isolated
+from each other. The API binds to localhost by default and uses one full-admin
+key; local sessions can read that key through the CLI. Backbone keeps its
+control-plane secrets out of launched environments, but this is not a filesystem
+security boundary. Read [Security](docs/security.md) before granting access or
+exposing the API.
+
+## Development
+
+```bash
+git clone https://github.com/eandualem/agent-backbone
+cd agent-backbone
+make install
+make check
+BACKBONE_DATA_DIR=/tmp/backbone-dev make dev
+```
+
+`make dev` runs on its own tmux server, so its agents stay apart from your own
+tmux sessions and from a real backbone's agents. Run CLI commands for it from
+a terminal outside tmux with the same settings, for example
+`TMUX_TMPDIR=/tmp/backbone-dev-tmux-$(id -u) BACKBONE_DATA_DIR=/tmp/backbone-dev uv run backbone agent attach NAME`.
+`agent attach`, and agent commands run while `make dev` is stopped, use tmux
+directly.
+
+See [Contributing](CONTRIBUTING.md) for branches, checks and releases.
+
+## License
+
+[MIT](LICENSE).

{agent_backbone-0.2.0 → agent_backbone-0.3.0}/USAGE.md

@@ -1,15 +1,16 @@
 # Quick usage
 
-**Open this guide in your terminal: `backbone usage`** (`ab usage` works too).
+**Open this guide in your terminal: `backbone help usage`** (`ab help usage` works too).
 `backbone docs usage` opens the same page. Use `backbone --help` for all commands.
 
 Prefer an agent to handle setup? Point it to [README.md](README.md) and ask it
-to follow `backbone help setup`.
+to follow `backbone help setup`. For prerequisites and a first task, use
+[Getting started](docs/getting-started.md).
 
-## Start Backbone manually
+## Install and start Backbone
 
 ```bash
-uv tool install "agent-backbone[github-app]"
+uv tool install agent-backbone
 backbone init
 backbone service install          # start now and at login
 backbone status
@@ -22,11 +23,14 @@ Run `backbone doctor` if setup needs attention.
 
 ```bash
 cd ~/code/app
-backbone agent start --runtime codex --model gpt-6-astra:high
+backbone agent start --runtime codex
+backbone tell app "Summarise this repository in three sentences."
 backbone agent attach app         # open its terminal; Ctrl-b d detaches
-backbone agent start app          # continue its saved conversation if stopped
-backbone agent start app --fresh  # new conversation, same CLI and model
+backbone agent start app          # new conversation, same CLI and model
+backbone agent resume app         # continue its previous conversation instead
 backbone updates                  # latest progress from the team
+backbone skills list              # shared skills and which agents receive them
+backbone skills app               # the skills one agent gets, with their tags
 ```
 
 An already running agent stays running. Starting from its directory also finds
@@ -37,8 +41,8 @@ changing CLI without a model clears the old CLI's model setting.
 
 ```bash
 backbone updates                              # latest reports from the team
-backbone updates --agent Feynman               # one agent's latest report
-backbone updates --agent Feynman --history     # its earlier reports
+backbone updates --agent app                   # one agent's latest report
+backbone updates --agent app --history         # its earlier reports
 backbone updates show 12                       # full report and links (use an ID shown above)
 backbone updates --limit 20                    # a larger page
 ```
@@ -49,10 +53,12 @@ has not published one. Reading reports does not interrupt agents or ask them to
 produce one. `backbone status` shows whether agents are working; `backbone updates`
 shows what they say they have accomplished.
 
-In Telegram, use `/updates`, `/updates Feynman`, `/updates history Feynman`, or
-`/updates show 12`. Each new report is also posted automatically to the configured
-agents group and, for ordinary agents, the agent’s own topic, with buttons for the full report and team feed. Delivery retries
-when Telegram is unavailable; older reports from before this feature are not sent.
+In Telegram, use `/updates`, `/updates app`, `/updates history app`, or
+`/updates show 12`. New reports appear in General and the ordinary agent's topic,
+with buttons for the full report and team feed. Delivery retries when Telegram
+is unavailable. Swarm participants send findings to their repository agent,
+which publishes the consolidated report. Optional voice messages need
+[local speech setup](docs/report-audio.md).
 
 ## Publish your progress (for agents)
 
@@ -67,39 +73,46 @@ The author defaults to the current agent; use `--agent NAME` outside an agent
 session. Reports must be short; oversized reports are rejected. See
 `backbone help reports` for the section limits and when to publish.
 
+During long work, agents can read corrections themselves without waiting for
+terminal delivery: `backbone inbox` (or `--agent NAME`). After applying or
+superseding messages, use `backbone inbox --ack TOKEN ...`. Check between meaningful
+steps and before a commit or handoff. Details: `backbone help messaging`.
+
+For `--ack`, copy each complete `ack_token` from the inbox response. Numeric row
+IDs alone cannot acknowledge work; tokens prevent stale acknowledgements from
+consuming a different message after queue cleanup.
+
 ## Rename an agent
 
 Wait until the agent finishes its work, then:
 
 ```bash
-backbone agent stop planner
-backbone agent rename planner Feynman
-backbone agent start Feynman --attach
+backbone agent stop app
+backbone agent rename app backend
+backbone agent start backend --attach
 ```
 
 The directory, settings, watches and saved conversation ID stay with the agent.
 Use the new name in messages, scripts and external `for:` labels. Renaming requires
 a stopped agent; active swarm members cannot be renamed.
 
+## Read token usage
+
+```bash
+backbone usage                         # separate CLI conversations for each agent
+backbone usage --agent backend --current
+backbone usage session ID              # input, cache and output details
+backbone usage --since 1h --by model
+backbone usage --cost                  # optional standard API estimate
+```
+
+Use `--json` for data, or `backbone help token-usage` for sources and coverage.
+Unsupported sources are unavailable, not zero usage. Cost is separate from a
+subscription bill. [Full token usage reference](docs/token-usage.md).
+
 ## Find more
 
 - `backbone agent start --help` — command options.
 - `backbone templates list` — injected instructions you can inspect and edit.
 - `backbone docs index` — the [documentation reading guide](docs/INDEX.md).
 - `backbone docs usage` — this page from an installed package.
-
-Ordinary agent reports appear in General and the agent's topic, with separate
-delivery receipts. Swarm participants, including coordinators, cannot publish human-facing reports.
-Only their repository agent reports consolidated progress to the owner. Optional full-report voice messages can be enabled with
-`backbone config set telegram.report_audio true` after local speech setup.
-See `backbone docs report-audio` for the model, service, voice and FFmpeg setup.
-
-
-During long work, agents can read corrections themselves without waiting for
-terminal delivery: `backbone inbox` (or `--agent NAME`). After applying or
-superseding messages, use `backbone inbox --ack TOKEN ...`. Check between meaningful
-steps and before a commit or handoff. Details: `backbone help messaging`.
-
-For `--ack`, copy each complete `ack_token` from the inbox response. Numeric row
-IDs alone cannot acknowledge work; tokens prevent stale acknowledgements from
-consuming a different message after queue cleanup.

{agent_backbone-0.2.0 → agent_backbone-0.3.0}/docs/INDEX.md

@@ -1,8 +1,10 @@
 # Documentation index
 
-Start with [Quick usage](../USAGE.md) for everyday commands. Each page is also
+New here? Start with [Getting started](getting-started.md) to install and send
+a first task. [Quick usage](../USAGE.md) covers everyday commands. Each page is also
 available as `backbone docs PAGE` after installation (for example,
-`backbone docs getting-started`). Filenames stay stable so saved links keep working.
+`backbone docs getting-started`). Installed help describes your installed version; GitHub pages describe the
+branch or tag you are viewing. Relative links keep you on that same revision.
 
 ## 1. Get started
 
@@ -12,9 +14,11 @@ available as `backbone docs PAGE` after installation (for example,
 
 ## 2. Run your team
 
+- [Token usage](token-usage.md) — per-agent CLI sessions, model tokens and optional API estimates.
 - [Report audio](report-audio.md) — optional local read-aloud in Telegram.
 - [Progress reports](reports.md) — goals, progress, blockers and next steps.
 - [Instruction templates](templates.md) — edit base, role and tag instructions.
+- [Skills](skills.md) — one shared store of skills, given to agents by tag.
 - [Deep reviews](deep-reviews.md) — run reviews in the background and retrieve findings.
 - [Swarms](swarms.md) — coordinate several agents on one task.
 - [Configuration](configuration.md) — settings, secrets and data locations.
@@ -25,6 +29,7 @@ available as `backbone docs PAGE` after installation (for example,
 - [GitHub](github.md) — issue routing and review notifications.
 - [GitHub App setup](github-app-setup.md) — configure webhook intake.
 - [Telegram](telegram.md) — talk to agents and read updates from your phone.
+- [Sources and subscriptions](sources.md) — agents subscribe to inbound events (Gmail) with filters and priority.
 - [API reference](api.md) — build scripts and dashboards.
 - [Integrations](integrations.md) — add another communication channel.
 
@@ -32,6 +37,9 @@ available as `backbone docs PAGE` after installation (for example,
 
 - [How it works](how-it-works.md) — follow requests through the system.
 - [Security](security.md) — trust boundaries and defaults.
+- [Signed senders and owner-confirmed messages](owner-confirmed-messages.md) —
+  how an app signs its requests and enrolls its key.
+- [Runtime capabilities](runtime-capabilities.md) — which capabilities work on which agent CLI.
 - [Status and roadmap](status-and-roadmap.md) — verified capabilities and remaining work.
 - [Contributing](../CONTRIBUTING.md) — development and checks.