# Teamster Demo — Agent Access Guide

This is a live, healthy Teamster observability demo (Grafana 13, anonymous
read-only access). The dashboard UI is a JavaScript app; a plain GET of this
page renders no dashboard content.

Start here — the data this demo holds, pre-rendered and refreshed hourly,
no request body required:

[https://teamster.bmj.net/public/llms/tour-snapshot.txt](https://teamster.bmj.net/public/llms/tour-snapshot.txt)

You are reading the short header of a longer guide, which continues below
this section with the data model, tag vocabulary, and dashboard reference.
It is also fetchable on its own, unchanged, at:

[https://teamster.bmj.net/public/llms.txt](https://teamster.bmj.net/public/llms.txt)

Every guide this demo publishes is served as `text/plain; charset=utf-8`, and
every guide URL in this document ends in `.txt`. Their contents are Markdown — the
plain-text content type is deliberate, because some agent web-fetch layers
reject `text/markdown` as an unsupported type and drop the response before
the model ever sees it. If your client would rather have `text/markdown`,
each per-dashboard guide is also served unchanged at the same path with a
`.md` extension.

The per-dashboard guides, listed in full so you can fetch one directly.
Each explains that dashboard's panels and the exact SQL behind them:

[https://teamster.bmj.net/public/llms/queries.txt](https://teamster.bmj.net/public/llms/queries.txt)  the thirteen tour queries, runnable as-is if you can POST
[https://teamster.bmj.net/public/llms/fleet-view.txt](https://teamster.bmj.net/public/llms/fleet-view.txt)  00 - Realtime Fleet View
[https://teamster.bmj.net/public/llms/fd-ai-spend-overview-v2.txt](https://teamster.bmj.net/public/llms/fd-ai-spend-overview-v2.txt)  01 - AI Spend Explorer
[https://teamster.bmj.net/public/llms/fd-cost-explorer-v2.txt](https://teamster.bmj.net/public/llms/fd-cost-explorer-v2.txt)  02 - AI Spend Trace
[https://teamster.bmj.net/public/llms/fd-usage-effectiveness-v2.txt](https://teamster.bmj.net/public/llms/fd-usage-effectiveness-v2.txt)  03 - Usage and Effectiveness
[https://teamster.bmj.net/public/llms/cost-by-tag-value.txt](https://teamster.bmj.net/public/llms/cost-by-tag-value.txt)  04.01 - Simple Cost Explorer
[https://teamster.bmj.net/public/llms/tag-stack-explorer.txt](https://teamster.bmj.net/public/llms/tag-stack-explorer.txt)  04.02 - Multidimension Explorer
[https://teamster.bmj.net/public/llms/entity-cost-explorer.txt](https://teamster.bmj.net/public/llms/entity-cost-explorer.txt)  04.03 - Work Explorer
[https://teamster.bmj.net/public/llms/fd-outcome-accounting-v2.txt](https://teamster.bmj.net/public/llms/fd-outcome-accounting-v2.txt)  05.01 - Outcome Accounting
[https://teamster.bmj.net/public/llms/outcome-cost-explorer.txt](https://teamster.bmj.net/public/llms/outcome-cost-explorer.txt)  05.02 - Outcome Explorer
[https://teamster.bmj.net/public/llms/fd-data-quality-v2.txt](https://teamster.bmj.net/public/llms/fd-data-quality-v2.txt)  09 - System Health
[https://teamster.bmj.net/public/llms/landing-page.txt](https://teamster.bmj.net/public/llms/landing-page.txt)  Teamster - Welcome (the human landing page)
[https://teamster.bmj.net/public/llms/activity-feed.txt](https://teamster.bmj.net/public/llms/activity-feed.txt)  zz - Realtime Activity Feed (deprecated, superseded by Fleet View)

Other GET endpoints, no authentication required:

[https://teamster.bmj.net/api/search](https://teamster.bmj.net/api/search)  dashboards: uid, title, tags
[https://teamster.bmj.net/api/dashboards/uid/landing-page](https://teamster.bmj.net/api/dashboards/uid/landing-page)  one dashboard's panels and SQL — a live example; the pattern is `/api/dashboards/uid/<uid>` for any uid from /api/search
[https://teamster.bmj.net/api/health](https://teamster.bmj.net/api/health)  liveness check
Live queries need POST, not GET, so most agents here cannot use this one. It is
deliberately not a link — a GET against it returns 404:
`POST https://teamster.bmj.net/api/ds/query`  read-only SELECT, JSON body

---

# Teamster — what this is, and what this instance contains

You are reading the context guide for a live **Teamster** instance. It explains
what the product is, what the data means, and how far to trust it. It contains
no queries: the numbers live in a companion document, and the two are meant to
be read together.

## The two documents

This demo publishes a matched pair. Each says what the other cannot.

**This document — the context guide**
[https://teamster.bmj.net/public/llms.txt](https://teamster.bmj.net/public/llms.txt)
What Teamster is, the problems it solves, what this particular instance holds,
and what every tag dimension means. No figures, because figures go stale; this
is the part that stays true.

**The data document — the instance's actual numbers**
[https://teamster.bmj.net/public/llms/tour-snapshot.txt](https://teamster.bmj.net/public/llms/tour-snapshot.txt)
Thirteen questions asked of the live database and answered, refreshed hourly.
Plain GET, no query tool required. Each section says what its result shape
means and points back here for what the terms signify.

Reading order is yours to choose, and both work:

- **To understand the product first**, read on. Four sections take you from
  what Teamster is to what its vocabulary means, and then the data document
  reads as confirmation rather than a wall of numbers.
- **To get to the numbers now**, go straight to the data document. It is
  self-contained enough to follow, and links back here whenever a term needs
  explaining.

If you only want one thing from either: the figures in the data document are
substantially **inferred rather than measured**, and its attribution section
quantifies exactly how much. That caveat is the single most important thing
this instance can tell you about itself.

The queries themselves, if you want to run them rather than read their results,
are published separately at
[https://teamster.bmj.net/public/llms/queries.txt](https://teamster.bmj.net/public/llms/queries.txt)
Running them requires an HTTP client that can POST a JSON body.

## What Teamster is for

Teamster is a self-hosted **AI observatory and cost-attribution system** for
coding agents (Claude Code and OpenAI Codex). Teams increasingly hand real
engineering work to fleets of AI agents and then discover they have no idea
what any of it cost, which work it went to, or whether it was any good. The
spend shows up as one opaque number on a bill. The work shows up as a pile
of commits. Nothing connects the two.

Teamster connects them. It records what every agent does in real time,
attributes per-message token spend to declared units of work, and makes the
result queryable along whatever dimensions you care about. Its organizing
promise is that **every dollar lands somewhere visible**: attributed cost
carries the method by which it was attributed, and whatever cannot be
attributed is reported as a visible residual rather than quietly dropped.

It exists to answer four questions:

1. **Where is the AI spend going?** — by product, work type, component, phase
2. **Who is spending it?** — engineers, and the agents they run
3. **What outcomes is it producing?** — cost per delivered unit of work
4. **Is it being used effectively?** — model fit, rework share, cache
   economics, healthy team patterns

## The problems it solves

- **Cost with no shape.** A monthly total tells you nothing actionable.
  Teamster tags work (product, feature, work type, component, team, engineer)
  and joins per-message token spend to those tags automatically — so you can
  ask "how much did feature X cost across all engineers," or "what share of
  our premium-model spend went to routine docs and tests." Retag work later
  and the numbers update retroactively.
- **Expensive models doing cheap work.** Model-fit analysis crosses model
  against work type, so a premium model quietly grinding through routine
  tasks becomes visible instead of just expensive.
- **Rework you can't see.** Cost is broken out by phase (design, build, test,
  review, rework). A rising rework-and-review share is an early signal of
  quality or coordination problems, well before it shows up as a missed date.
- **Agent teams as black boxes.** A live activity stream shows what every
  agent is reading, editing, running and thinking, so a team of agents is not
  just whatever the lead agent summarizes afterward.
- **Context burn.** A health collector tracks per-agent context-window
  pressure and cache economics, surfacing agents carrying so much context
  that quality is degrading and cache reads are inflating cost.
- **Attribution gaps.** Agents forget to declare what they're working on.
  Rather than pretending otherwise, Teamster runs recovery passes and labels
  each attribution with its method and confidence, so you can tell measured
  cost from inferred cost.

## What this particular instance is

This is a live demo carrying **real telemetry from daily agent work** — not a
synthetic dataset. Two consequences worth knowing before you draw conclusions:

**Most of the spend is Teamster building itself.** When you see
`product = Teamster`, that is the observability tool you are currently
querying, being developed by the same kind of agent teams it instruments. It
is the dominant product by spend and the richest seam in the data.

**Gaps are real, not broken.** The system is under continuous development.
Sparse or empty results for a narrow window, an unusual tag combination, or
a specific dashboard reflect genuine gaps in the underlying work — not a
failed query. Widen your time range before concluding something is wrong.

The other products you'll encounter under the `product` tag:

- **ScrollZ** — an IRC client.
- **homelab** — home network, compute, storage, and smart-home infrastructure.
- **job-search** — a job-application workflow toolkit.

Around fifteen `product` values exist in total (side projects, tooling,
one-offs), plus an `(untagged)`/`(unallocated)` bucket for cost not yet
attributed to any product. Treat the list above as "what you'll mostly see,"
not a closed set.

## How the data is organized

Cost and usage are attributed to work via key:value tags on **outcomes** (a
body of work, roughly a project or initiative) and **work units** (one agent
session's slice of that work). Slicing by these tags is how the data is made to
mean anything, and it is what every figure in the data document is grouped by.

The table below covers the keys that matter for analysis. It is not the whole
set — roughly two dozen keys are in live use, including provenance keys such as
`git.branch`, `github.repo` and `runtime` that are recorded automatically
rather than declared. The data document reports the live set and how much spend
each key can account for.

| Key | Meaning | Shape |
|---|---|---|
| `product` | Which project the work belongs to | ~15 values — see the product dictionary below |
| `team` | Which agent team ran the session | Ad-hoc per-session callsigns, ~90+ distinct values. Free text, not a lookup table. |
| `component` | Subsystem touched | ~60 values: `dashboard`, `hookd`, `wms`, `installer`, `store`, `pricing`, `tokens`, `collectors`, `boot-chain`, `demo`, `monitoring`, `cli`, `docs`, … |
| `work-type` | What *kind* of work it is | Controlled — see the work-type dictionary below |
| `phase` | Where in the work lifecycle the cost fell | Controlled — see the phase dictionary below |
| `priority` | Urgency | `p0` (highest) … `p3` |
| work-scope slugs | *Which specific* thing was worked on | One key per work type: `feature:`, `bug:`, `refactor:`, `infra:`, `research:`, `docs:`, `test:`, `admin:`, `rework:`. At most one applies to an outcome. |

**A note on work-scope slugs.** These are the one family of tags whose
*values* are not a vocabulary to learn. `product`, `work-type` and `phase`
have controlled value sets that mean something in themselves — those are
documented below. A work-scope slug value is just an identifier for one
particular piece of work (`bug:<something>` names one specific bug), so the
hundreds of distinct values carry no class meaning and there is nothing to
memorize. What matters is the key: `bug:` means "this outcome is about a
specific defect," `research:` means "one specific research effort," and so
on — the slug key matches the `work-type` of the work, and carries the same
meaning that work-type does.

Use them to group and drill rather than to interpret: counting distinct slug
values under a key tells you how many separate efforts a work type covers, and
filtering to one isolates everything spent on a single piece of work. The data
document does both.

### Product dictionary — what the projects in this data actually are

Filter or group by `product` to compare these. Roughly: the Teamster family
dominates by spend, the rest are the operator's other AI-assisted projects.

| `product` | What it is |
|---|---|
| `Teamster` | The AI observatory / cost-attribution product itself — the tool you are querying. The largest ongoing effort by spend. |
| `teamster-demo` | This demo system: disposable replica hosts that rebuild from scratch on every boot, plus the delivery pipeline that feeds them. Distinct from the product. |
| `teamster-manager` | `tm` — the CLI managing Teamster's public/private repo split, feature branches, and release publishing. |
| `teamsters-union` | Extending agent-team support to other agent runtimes (Codex, Gemini) plus per-agent health telemetry. |
| `muster` | Agent roster and health telemetry: who is running, liveness, context pressure. |
| `anchor` | A vendor-agnostic IRC-based multi-agent coordination harness (prior art / experiment). |
| `pibox` | Productizing the "disposable Pi" pattern — durable storage stages the install, all runtime state lives on tmpfs and is rebuilt each boot. |
| `ScrollZ` | An IRC client (C codebase). |
| `homelab` | Home infrastructure: network, compute, storage, smart home. |
| `job-search` | A job-application workflow toolkit. |
| `sb` | A personal knowledge vault and its automation harness. |
| `helmsman` | A modern TradeWars 2002 helper desktop client. |
| `TradeWars` | Hosting and running TradeWars 2002 game servers and tournaments. |
| `PizzaLab` | A prime-sieve benchmark project used to exercise agent-team coordination. |
| `procps` | Work on the `procps-ng` process utilities suite. |

### Work-type dictionary — what kind of work the money bought

`work-type` is the most useful lens for "are we building, fixing, or
thrashing?" These definitions are the ones the system classifies against.

These are the definitions the system classifies against, verbatim. Several
are written as explicit contrasts with their neighbours — `research` vs
`investigation`, `docs` vs `research`, `feature` vs `bug` vs `refactor` —
so read the exclusions, not just the first clause. Seven are the required
canonical set; the rest are permitted but not enforced.

| `work-type` | Canonical | Definition |
|---|---|---|
| `feature` | yes | Adds a new capability that did not exist before: a new endpoint, panel, column, command, or integration. Title starts Add/Implement/Build/Create/Support and the result is new. NOT fixing broken behavior (bug), NOT restructuring code (refactor). |
| `bug` | yes | Fixes incorrect existing behavior, a defect in something that already exists. Title starts Fix/Repair/Correct/Resolve, or restores a broken panel/metric/label. NOT adding something new (feature), NOT tooling/infra changes (infra). |
| `refactor` | yes | Restructures existing code without changing its external behavior (cleanup, extraction, renaming). |
| `infra` | yes | Infrastructure, build, deploy, CI, provisioning, host setup, or schema/migration plumbing: tooling/substrate, not user-facing behavior. Title: host setup, install/CI/systemd, DB schema scaffolding, exporter wiring. NOT a product capability users invoke. |
| `research` | yes | Investigation, audit, or synthesis whose output is knowledge (a finding or recommendation), not code or docs. Title starts Investigate/Recon/Audit/Explore/Evaluate/Inspect/Synthesize/Diagnose. Synthesis is research even under a docs/build outcome. |
| `docs` | yes | Authoring or rewriting documentation as the deliverable: README, architecture doc, spec, guide, comments. Output is the prose itself; title names a doc file or says write/rewrite/document. NOT investigation that feeds a doc (that is research). |
| `test` | yes | Validation run: exercising a deployed system end-to-end to confirm it behaves correctly. Apply when the primary output is a pass/fail verdict on deployed behavior, not new code. |
| `admin` | no | Administrative effort to maintain the product itself: branch consolidation, release prep, repo hygiene, version management. NOT feature/bug/infra/docs work. |
| `security` | no | Security audit, hardening, threat modeling, attack surface reduction. Output is findings and recommendations, not code. Distinct from research (security-specific framing) and infra (may propose infra changes but the work itself is assessment). |
| `processor` | no | Rote, rule-based or LLM-driven data processing run on a schedule, queue, or per-item basis — the deliverable is processed/classified data, not a human-facing capability or a finding for a human. NOT admin (human-directed repo/release maintenance), NOT research (research yields a finding or recommendation for a human), NOT infra (infra is tooling/substrate, not the processing job itself). |
| `polish` | no | Refinement and sync of existing artifacts — upserts, visual polish, consistency passes. Not new capability (feature), not fixing broken behavior (bug). |
| `investigation` | no | Exploratory investigation into system behavior or issues. **Distinct from `research`:** research produces a finding or recommendation as its deliverable; `investigation` is the exploratory activity itself. |
| `ops` | no | Operational task — applying changes to live infrastructure. |
| `review` | no | Code review of an implementation. |

`bugfix`, `build`, `design` and `rework` also appear as `work-type` values in
older records and carry no definition in the vocabulary — treat them as
unclassified rather than guessing their intent. Note `design`, `build`,
`review` and `rework` are properly *phase* values; where they appear as a
work-type they predate the split.

### Phase dictionary — where in the lifecycle the cost fell

`phase` is what makes rework visible. Comparing `rework` + `review` against
`build` is the single most informative ratio in this dataset.

Definitions verbatim, as with work-type.

| `phase` | Canonical | Definition |
|---|---|---|
| `design` | yes | Design or planning before implementation: shaping the approach, writing the spec/plan. Apply while the task is figuring out WHAT and HOW, before code is written. |
| `build` | yes | Implementation: writing the code/content that satisfies the task. Apply once the task moves from planning into producing the change. |
| `test` | yes | Verification: running tests, exercising behavior, confirming the change does what the task says. Apply during the VALIDATE phase of the execution loop. |
| `review` | yes | Adversarial review of a completed change by someone other than the author. Apply during the REVIEW phase, before commit. |
| `rework` | yes | Work redone after a review or validation sent it back. Apply when an entity re-enters an earlier phase to fix problems found downstream — distinguishes first-pass cost from correction cost. |
| `admin` | yes | Orientation/warmup/coordination cost before the session declared a work focus. |
| `exec` | no | Execution of an autonomous, scheduled/queued processing job with no design/build/test/review loop of its own — the whole unit of work IS the execution (pairs with `work-type:processor`). Apply to work units created by cron-run or timer-driven automation rather than a human- or LLM-directed dev task. NOT admin (admin is pre-focus orientation/coordination cost within an otherwise normal session), NOT build (build is implementation work within a design→build→test→review loop). |

`research`, `investigate`, `implementation` and `skipped` also occur as
`phase` values but carry no definition in the vocabulary — treat them as
unclassified rather than inferring intent from the word.

**Reading this data well:** a healthy stretch of work shows most cost in
`build` with modest `design`/`review`. A large `rework` share, or `admin`
dominating, is the signal Teamster exists to surface — the first says quality
or briefing problems, the second says coordination overhead is eating the
budget.

## How much of this is measured, and how much inferred

This is the part to carry away, because it qualifies every number this instance
can produce.

Agents are supposed to declare what they are working on. In practice they often
do not, so Teamster runs recovery passes that reconstruct the link afterwards —
reading session transcripts, booking pre-focus orientation cost, filling gaps,
and, where nothing else can be established, synthesizing a placeholder. Each
attributed dollar records which of those methods produced it.

Two distinct claims follow, and they are easy to conflate:

- **Nothing is dropped.** Billed cost and attributed cost agree; there is no
  pool of spending that quietly failed to land anywhere. Teamster's organizing
  promise is that every dollar lands somewhere visible.
- **Most of it is inferred.** Direct measurement — a message falling inside a
  declared focus interval — accounts for a minority of spend on this instance.
  The large majority is reconstructed after the fact.

The second claim is not a defect being concealed; it is the defect being
reported. An attribution system that publishes its own method mix is one you can
argue with, rather than one you must trust blindly. The data document's
attribution section carries the live split, and it is the authority — the set of
recovery methods grows over time, so any list written down here would rot.

When you quote a figure from this instance, quote the method mix with it.

## Appendix — per-dashboard reference

The demo's human-facing dashboards each have a reference file describing what
every panel computes. These answer a narrower question than anything above:
not "what does this data mean" but "what exactly is behind panel X." Reach for
one when you want to reproduce or audit a specific number a dashboard shows.
Fetch only the one you need — they are long.

Each file documents a panel's query as that panel computes it, so the shapes
differ from the data document's. Panels carry their own bucketing — hourly in
some, a single whole-window total in others — along with their own variable
substitution and filtering. Several deliberately stop short of the last 24
hours so attribution has time to catch up, and at least one counts from the
window start onward with no upper bound at all. Where a panel differs, the
difference is intentional and usually the point.

The **Title** column is the exact string the demo's dashboard-search endpoint
returns, numeric prefix and all, so a title can be matched to a guide without
guessing. The **uid** is what identifies a dashboard in its URL.

Every guide below is served as `text/plain; charset=utf-8` — Markdown contents
under a plain-text content type, so that a fetch layer which rejects
`text/markdown` can still read them. Each is also served unchanged at the same
path with a `.md` extension if your client prefers that type.

| Title (exactly as the search API returns it) | uid | What it answers | Guide |
|---|---|---|---|
| 00 - Realtime Fleet View | `fleet-view` | What every agent is doing right now | [https://teamster.bmj.net/public/llms/fleet-view.txt](https://teamster.bmj.net/public/llms/fleet-view.txt) |
| 01 - AI Spend Explorer | `fd-ai-spend-overview-v2` | The executive view: headline spend, trend, who spent it | [https://teamster.bmj.net/public/llms/fd-ai-spend-overview-v2.txt](https://teamster.bmj.net/public/llms/fd-ai-spend-overview-v2.txt) |
| 02 - AI Spend Trace | `fd-cost-explorer-v2` | Deep analysis: pick any three tag dimensions and trace spend across them | [https://teamster.bmj.net/public/llms/fd-cost-explorer-v2.txt](https://teamster.bmj.net/public/llms/fd-cost-explorer-v2.txt) |
| 03 - Usage & Effectiveness | `fd-usage-effectiveness-v2` | Are we using AI *well*? Model fit, rework tax, cache economics | [https://teamster.bmj.net/public/llms/fd-usage-effectiveness-v2.txt](https://teamster.bmj.net/public/llms/fd-usage-effectiveness-v2.txt) |
| 04.01 - Simple Cost Explorer | `cost-by-tag-value` | Cost broken down by any single tag dimension | [https://teamster.bmj.net/public/llms/cost-by-tag-value.txt](https://teamster.bmj.net/public/llms/cost-by-tag-value.txt) |
| 04.02 - Multidimension Explorer | `tag-stack-explorer` | Two-level hierarchy, cost matrix, phase waterfall | [https://teamster.bmj.net/public/llms/tag-stack-explorer.txt](https://teamster.bmj.net/public/llms/tag-stack-explorer.txt) |
| 04.03 - Work Explorer | `entity-cost-explorer` | Cost by individual outcome or work unit | [https://teamster.bmj.net/public/llms/entity-cost-explorer.txt](https://teamster.bmj.net/public/llms/entity-cost-explorer.txt) |
| 05.01 - Outcome Accounting | `fd-outcome-accounting-v2` | Cost per delivered outcome, and attribution confidence | [https://teamster.bmj.net/public/llms/fd-outcome-accounting-v2.txt](https://teamster.bmj.net/public/llms/fd-outcome-accounting-v2.txt) |
| 05.02 - Outcome Explorer | `outcome-cost-explorer` | Per-outcome drill-down | [https://teamster.bmj.net/public/llms/outcome-cost-explorer.txt](https://teamster.bmj.net/public/llms/outcome-cost-explorer.txt) |
| 09 - System Health | `fd-data-quality-v2` | Pipeline health and data quality | [https://teamster.bmj.net/public/llms/fd-data-quality-v2.txt](https://teamster.bmj.net/public/llms/fd-data-quality-v2.txt) |
| Teamster — Welcome | `landing-page` | The human landing page | [https://teamster.bmj.net/public/llms/landing-page.txt](https://teamster.bmj.net/public/llms/landing-page.txt) |

**Two reconciliations, so the search API does not surprise you.**

The search API returns one dashboard this table omits: `activity-feed`,
"zz - Realtime Activity Feed (deprecated)". It is superseded by the Fleet View,
which shows the same event log under a live agent roster, and its own guide at
[https://teamster.bmj.net/public/llms/activity-feed.txt](https://teamster.bmj.net/public/llms/activity-feed.txt) opens by saying so. It is
listed here only so you know why it is not listed above.

You may also see references elsewhere to Claude Code Metrics and Codex Metrics
dashboards. Those are **not present on this demo** and querying for them will
find nothing. They are built entirely on Prometheus/OTEL metrics, and only the
MySQL database replicates to demo hosts — so they would render empty here and
are removed at boot rather than shipped broken. Nothing else in this guide
depends on them.

To view any dashboard as a human would, put its uid in the path:
[https://teamster.bmj.net/d/fd-ai-spend-overview-v2](https://teamster.bmj.net/d/fd-ai-spend-overview-v2) — with controls set via
query string, for example
[https://teamster.bmj.net/d/tag-stack-explorer?var-stack_level_1=product&var-stack_level_2=work-type](https://teamster.bmj.net/d/tag-stack-explorer?var-stack_level_1=product&var-stack_level_2=work-type)