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

{agent_backbone-0.1.0 → agent_backbone-0.3.0}/.gitignore

@@ -18,6 +18,10 @@ coverage_html/
 *.db
 *.db-journal
 
+# Backbone-local, never shared: swarm worktrees and the agents' shared memory
+# (.backbone/memory — see AGENTS.md)
+.backbone/
+
 # Editors / OS
 .idea/
 .vscode/

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.3.0/USAGE.md

@@ -0,0 +1,118 @@
+# Quick usage
+
+**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`. For prerequisites and a first task, use
+[Getting started](docs/getting-started.md).
+
+## Install and start Backbone
+
+```bash
+uv tool install agent-backbone
+backbone init
+backbone service install          # start now and at login
+backbone status
+```
+
+Without a login service (for example, in a container), use `backbone up --detach`.
+Run `backbone doctor` if setup needs attention.
+
+## Work with an agent
+
+```bash
+cd ~/code/app
+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          # 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
+its registered name. Choose `--runtime` and `--model` explicitly to change them;
+changing CLI without a model clears the old CLI's model setting.
+
+## Read agent progress
+
+```bash
+backbone updates                              # latest reports from the team
+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
+```
+
+When a page has more results, it prints the command for the next page. Reports
+show goals, progress, blockers and next steps. “No report yet” means that agent
+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 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)
+
+```bash
+backbone report --example > progress.json
+# Replace the example with your goal, progress, blockers and next steps.
+backbone report --file progress.json --validate
+backbone report --file progress.json
+```
+
+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 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.

agent_backbone-0.3.0/docs/INDEX.md

@@ -0,0 +1,50 @@
+# Documentation index
+
+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`). 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
+
+1. [Getting started](getting-started.md) — install, start agents and send a message.
+2. [Concepts](concepts.md) — names, runtimes, states and delivery conditions.
+3. [CLI reference](cli.md) — start, resume, attach, rename and configure agents.
+
+## 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.
+- [Diagnostics](diagnostics.md) — investigate failures, retries and startup problems.
+
+## 3. Connect other tools
+
+- [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.
+
+## 4. Understand and contribute
+
+- [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.
+
+## Help, templates and media
+
+[Help](../help/) contains short playbooks agents request with `backbone help`.
+[Templates](../templates/) contains instructions injected at launch.
+[Media](media/) contains documentation illustrations and recordings.

agent_backbone-0.3.0/docs/README.md

@@ -0,0 +1,7 @@
+# Documentation
+
+Open [INDEX.md](INDEX.md) for the reading order and grouped reference pages.
+For everyday commands, start with [Quick usage](../USAGE.md).
+
+Installed package: `backbone docs index` or `backbone docs usage`.
+Agent playbooks: `backbone help`. Injected instructions: `backbone templates list`.