# The whole system

URL: https://services.dev/docs/start/system

> One Service({...}) becomes a whole business. The file, the objects it creates, the two rules that hold them together, and how the Service and services.dev earn.

Describe the work in one `Service({...})`. Place people where you want them; by default there are none, and AI delivers every job. Sell it everywhere: the file becomes your API, CLI, MCP server, SDK, site, docs and an app for everyone in the job.

## The whole system, in one file

Translation, grown: a sworn translator signs, the registry files it, and a renewal date outlives the job. Each comment names the object a key creates:

```ts title="services/translation.ts"
export default Service({ // Service
  name: 'Translation',
  input: { document: 'file', to: 'language', client: 'party' }, // Parties
  output: { document: 'file', filing: 'text' },
  rules: rules(), // Rules: sign is reserved
  roles: { translator: { pool: translators(), pay: 30 } }, // Pool, and its Tasks
  deliver: { // Steps, each committed by the Gate
    translate: 'ai',
    harden: { review: 'adversarial', lenses: ['meaning', 'terms'] },
    sign: { by: 'translator', stamp: true }, // Task: a member signs
    file: { submit: 'https://registry.example.test/filings', receipt: 'filing' },
  },
  subject: { kind: 'filing', key: 'filing' }, // Subject
  clocks: { renewal: { due: '1y after file', owner: 'buyer', lives_on: 'subject' } }, // Clock
  price: { usd: 89, release: 'file' }, // Money: charged on the receipt
})
```

Fourteen lines, and every object on the map is in them or made from them: each order is a Job with its Record, the Surfaces and apps are generated, and the Brand is the one file beside it.

- Define: **Brand** (domain · words · credentials · fees) owns **Service({...})** (input · output · steps · price) bound by **Rules** (reserved · open · refused)
- Generate: **Surfaces** (API · CLI · MCP · SDK · Site · Docs) and **Apps** (customer portal · delivery portal · owner console)
- Order: **Buyer** (a person, or their agent) orders **Job** (record · ledger · parties · clocks)
- Deliver: **Steps** (work · review · ask · submit) propose to **Gate** (graph · mechanics · merits · authority · proof) commits to **Record** (append-only, the one source of status)
- People: **Role step** (the act a credential covers) posts **Task** (offered, never assigned, fee fixed at post) to **Pool** (members, eligibility, dispatch, pay, door)
- Money: **End** (delivered · accepted · a receipt · a won deal) releases **Charge** (held until its fact is on the record) splits on **Ledger** (pay · pass-through · AI · fee · your margin)
- Time: **Subscription** (a schedule or an event) mints Jobs on **Subject** (kept facts · periods · who is of record) carries **Clocks** (dates the world sets, with rungs)

**One business, many brands.** `brand.ts` renames the core in the business's words (a job is a matter, a member a signer), and several brands can sell the same Services from one Pool:

```bash
npx services.dev check
```

```txt title="magic values: none"
brand.ts · 10 lines · legal · api.lawyer · words job → matter, subject → asset, task → review, member → signer, pool → network, end → outcome
```

## Two rules hold it together

**Every doer proposes, and the gate commits.** AI, a person, your code and another Service reach the record the same way. Each one proposes, and the gate checks the proposal before it writes. An AI draft and a licensed signature carry the same kind of evidence, and a key that tries a person's act is refused the same way every time.

**Every surface renders one contract.** The API, the CLI, the MCP server, the SDK, the site, the docs and the apps are renderings of the same [registries](https://services.dev/docs/surfaces/contract.md). No surface renames anything. `Brand.words` is the one renaming, and you declare it.

## How it earns

Every Service states its price, and every charge waits for the fact it names: delivery, acceptance, a receipt or a verified outcome. When it releases, one ledger splits it, and the buyer, you and each member read the same lines:

**you = charge − tax − processing − AI − pay − pass-through − coverage − placement − nested Services − services.dev's take**

services.dev's take falls on the value your brand adds, less on higher plans. It never touches pay, a pass-through, placement or a licensed fee, and an uncharged job pays none. [Your plan](https://services.dev/docs/money/plans.md) decides which keys run on live jobs:

| Plan | For | Adds |
|---|---|---|
| Free | Sell your first Service | Every surface and app, on your builder.domains address; Every review pattern, at any depth; All seven asks, filings with receipts, and clocks on the job; You and two staff as signers; Per job, per unit, tier, self-help and approval prices |
| Launch | Your name, your people, work that recurs | Your own domain on every surface; Your own Pool of five, a rented one, or yours on an existing door; Payout schedules, with a hold on new members; Subjects, kept facts, clocks that outlive the job, subscriptions; Outcome pricing, pay at the win, and a sample that falls |
| Team | Run a market, paid on the win | Pools to 50, with cascade, tiers, golden Tasks and firms; A door of your own, with a demand board; Standby for a dated season, and one Pool across brands; Share pay to members, and the custodian ladder; Tenants, Rules across regions, staff SSO and custom roles |
| Scale | Pass the buyer's review | Unlimited members in Pools you own; SCIM, audit export and SIEM; Private deploys and data regions; Practice workspaces; Your Pool, exported for other operators |

`check` names the plan live jobs need, line by line:

```txt
$ npx services.dev check
services/translation.ts · 14 lines · $89 per job, within 48 hours, charged on file's receipt.
  plan    Launch (services.dev) · roles.translator.pool at services/translation.ts:6 · subject at :13 · clocks at :14
          every key runs in test on any plan · deploy --live asks for Launch
  take    your plan's take on each released charge · never on the translator's $30.00
```

Sign the act yourself, with no `pool`, keep the clock on the job, and it sells on Free. [Money](https://services.dev/docs/money.md) is how a Service earns and pays, line by line.

## The default, and what each key adds

With input, output and a price, a Service has one AI step and one adversarial review, and it's charged on delivery. No person touches it. Everything else is one key you add:

| You add | The business gains | Shape | Live on |
|---|---|---|---|
| [`review`](https://services.dev/docs/grow/review.md) lenses and rounds | a draft hardened before it ships | lingua | Free |
| [an `ask`](https://services.dev/docs/grow/ask.md) | the buyer or client signs, consents, answers, uploads, decides or grants | any | Free |
| [`human: 'risky'`](https://services.dev/docs/people.md) | a person you choose looks at the jobs the review flags | lingua | Free |
| [`rules` and a `role`](https://services.dev/docs/grow/role.md) | a credentialed person performs the reserved act: licensing met by design | api.lawyer | Free when you sign; Launch with a Pool |
| [a `submit`](https://services.dev/docs/grow/submit.md) | filings with typed receipts, routed rejections and repair windows | api.lawyer, apis.tax | Free |
| [`clocks` on the job](https://services.dev/docs/grow/clock.md) | dates the world sets, acted on before each one | apis.tax | Free |
| [a `subject` and its clock](https://services.dev/docs/service/subject.md) | obligations that run for years | apis.tax | Launch |
| [`price` forms and an `outcome`](https://services.dev/docs/money.md) | every way the work earns, each released on a fact | api.forsale | Free per job; Launch for an outcome |
| [a Pool's tiers and firms](https://services.dev/docs/people/pool.md) | a market of members, ranked by their record | any with people | Team |

## Next

**[Services as software](https://services.dev/docs/start/why.md)**: why the finished job is what you sell, and the one question that decides it.

# Services as software

URL: https://services.dev/docs/start/why

> Most paid work is a known sequence of steps. A Service sells the finished job, delivered by AI, with people where you want or need them, and buyers and their agents pay when it's done.

You know a kind of work people pay for: a filing, a return, a booked meeting, a reviewed claim. Most of it is a known sequence of steps. Gather the facts, draft, check, sign where the law says, file, and get paid. AI now does most of those steps well, and a review pass on every job costs cents. So the finished job, not the hour, is what you sell, and software can stand behind it.

## The glue is the hard part

The AI isn't what stands between you and that business. The glue is: a workflow engine, a review queue, a market of credentialed people, payments, payouts, a site, an API, an MCP server, docs and two portals, all before the first paid job. services.dev is that layer. One `Service({...})` generates all of it, under your brand.

- **AI delivers every job by default.** With no `human` line, no person touches it.
- **People come in where you want or need them.** A reviewer on the jobs a review flags, because you want one there. A signature only a credentialed person may give, because the work requires it. A credentialed step meets licensing by design.
- **Buyers pay when it's done.** People, and the agents that buy for them, order a finished job at a price. An agent can buy a job; it can't hire by the hour.

## What every Service states

What comes in, what goes out and what it costs are required: leave `price` out and your editor says `Property 'price' is missing.` The rest defaults: delivered within 48 hours, charged on delivery or on the last submit step's receipt, done by AI with an adversarial review, and no person until you write `human` ([every key](https://services.dev/docs/service/fields.md)). Every surface prints the terms they add up to:

```txt
translation · $49 per job, within 48 hours, charged on delivery.
  terms   Charged on delivery. Cancel at $0 until it ships. Send it back with a note and the AI redoes it, or you pay $0. Final 7 days after delivery.
```

The market's word for this is an SLA. Here the terms aren't a document beside the work: they're written from the Service itself, so they can't say more than it does, and they grow with it. Add a signer and a registry filing, and the line reads:

```txt
filed-translation · $89 per job, within 48 hours, charged on file's receipt.
  terms   Charged on file's receipt. Cancel at $0 until file is done, except the work a person attested once the signature before file is done. Send it back with a note and the AI redoes it, or you pay $0. Final 7 days after delivery.
```

## What it isn't

| It isn't | Because | What a Service does with it |
|---|---|---|
| A tool the buyer runs | A tool hands the work back: the buyer still does the job, faster | Runs the tool as a step and sells the result |
| Hours of someone's time | Hours make the buyer manage the work | Prices the job, and pays a person per act at the steps you place them |
| A record or an answer from an API | Software and data sold as a service are building blocks: they answer one question and stop | Calls them as steps, with your code, a URL or a submission, and sells what they add up to |
| A queue of tasks for your team | A queue is how work moves inside a business, not what a buyer pays for | Keeps the queue inside the job, behind one price and one deadline |

A record can still be the whole Service when the record is the finished work: the Service submits the request, holds the order, and charges on the receipt.

## What it changes

Buyers and their agents order at any hour, AI delivers most jobs in minutes, and your margin grows as AI takes more of the steps.

## One question decides

Ask who holds the work until it's done. If the answer is the buyer, it's a tool, a feed or a team. If it's you, write it as a Service. Work AI finishes alone starts at [your own Service](https://services.dev/docs/own.md). Work that needs a credentialed signature starts at [the shape it resembles](https://services.dev/docs/start/shapes.md).

## Next

**[How a job runs](https://services.dev/docs/start/how-it-runs.md)**: one order, carried through six stops from the first input to the last cent.

# human: the line

URL: https://services.dev/docs/people

> Where a person comes in, if anywhere. Leave it out and AI delivers every job alone. Draw the line where you want a person, and where the work needs one, name the role and let the rules decide the act.

Leave `human` out and AI delivers every job alone. Add it and you draw **the line**: the point where a job goes to a person before it ships. Each form is one edit, and `check` reads it back.

## Where you want a person

| `human:` | `check` prints |
|---|---|
| left out | AI delivers every job. |
| `'risky'` | A person approves the jobs the review flags, before delivery. |
| `'always'` | A person approves every job before delivery. |
| `{ when: job => job.input.to.startsWith('ja'), because: 'Japanese jobs' }` | A person approves Japanese jobs before delivery. |

Your own rule says why in `because`. [A sampled line](https://services.dev/docs/people/sample.md) checks a share of delivered jobs, falling while send-backs stay rare.

### The rungs

Each step stands on one rung, from the most hands to none:

| Rung | `human:` | What a person sees |
|---|---|---|
| every job | `'always'` | every job, before delivery |
| a sample after delivery | `{ sample, floor }` | a share of delivered jobs, falling while send-backs stay rare |
| flagged, and a sample of the rest | `{ when: 'risky', sample }` | the jobs the review flags, before delivery, and a share of the rest after |
| flagged | `'risky'` | the jobs the review flags, before delivery |
| AI alone | left out | nothing: AI delivers every job |
| reserved | the act your [rules](https://services.dev/docs/people/rules.md) reserve | every job, at that act. It never moves |

A step moves between rungs on the record: [Move a step to AI](https://services.dev/docs/operate/line.md).

A job at the line waits for a person, in your app or in the terminal:

```bash
npx services.dev dev
```

```txt title="captured"
an agent ordered Translation at $49
job_7Hq2 · waiting · on approval · $49.00 held
  record  draft · ai | review · ai · pass
  next    npx services.dev approve job_7Hq2
```

```bash
npx services.dev approve job_7Hq2
```

```txt title="captured"
job_7Hq2 · delivered · document.fr-CA.pdf · $49.00 charged
  record  draft · ai | review · ai · pass | approve · person
  ledger  +$49.00 · AI $0.84 · you $48.16
  next    npx services.dev accept job_7Hq2
```

Only a person approves, in the app. An API key or an MCP tool that tries gets [`needs_a_person`](https://services.dev/docs/reference/errors.md#needs_a_person). To let the buyer decide instead, [sell a person's approval](https://services.dev/docs/money/prices.md#eight-forms).

## Where you need a person

Some work needs a credential. `sign` names it, `in` names the input that holds the job's jurisdiction, and `before` names the step the signer signs before:

```ts
export default Service({
  name: 'Certified Translation',
  input: { document: 'file', to: 'language: such as fr', country: 'jurisdiction: such as FR' },
  output: { document: 'file', certificate: 'file' },
  deliver: { translate: translation, certify: 'ai' },
  human: { sign: 'sworn-translator', in: 'country', before: 'certify' },
  price: { usd: 189, payout: 60, within: '3d' },
})
```

```bash
npx services.dev certified-translation document=birth-certificate.pdf to=fr country=FR --max 189
```

```txt title="captured"
job_7Hq3 · working · $189.00 held
job_7Hq3 · waiting · on signature · $189.00 held
  record  translate · service · job_7Hq4 · $49.00 | review · ai · pass
  next    npx services.dev approve job_7Hq3
```

```bash
npx services.dev approve job_7Hq3
```

```txt title="captured"
job_7Hq3 · delivered · birth-certificate.fr.pdf · certificate.pdf · $189.00 charged
  record  translate · service · job_7Hq4 · $49.00 | review · ai · pass | sign · sworn translator · FR | certify · ai
  ledger  +$189.00 · AI $0.84 · your Translation $49.00 · sworn translator $60.00 · you $79.16
```

That line is shorthand for one role and one step. Licensed work grows it into [Rules](https://services.dev/docs/people/rules.md), your counsel's table of which acts are reserved to a credential, which is how a Service meets licensing by design; [roles](https://services.dev/docs/people/roles.md), who holds the credential and where; and [a Pool](https://services.dev/docs/people/pool.md), the people who fill a role.

The legal example's contract review, as `check` reads it:

```bash
npx services.dev check
```

```txt title="magic values: none"
services/contract-review.ts · 16 lines · $99 per job, within 48 hours, charged on acceptance.
  who     An attorney admitted where the client is signs every memo before delivery. (rules 2026-10) The client consents first.
  roles   attorney · bar admission · from attorneys · $50 an act
  bounds  reserved advise to bar admission where the client is, in US-CA, US-NY and US-TX only · the attorney sells the fee · open send · refused litigate
```

The AI drafts and attacks the memo, and an attorney admitted where the client is advises. [What a person can do](https://services.dev/docs/people/acts.md) lists each act, and [Refusals and cures](https://services.dev/docs/people/refusals.md) what every caller hears when the rules say no.

## Who does the step

Every step has one doer. AI does every step it can, and each rung up is one line:

| Who does the step | One line | Paid | Plan | In apis.tax |
|---|---|---|---|---|
| [AI](https://services.dev/docs/service/ai.md) | `human` left out | AI, at cost | Free | `draft`, `check` |
| [Your code](https://services.dev/docs/service/code.md) | `by:` a function | nothing | Free | `compute`, `tentative` |
| [The buyer or a party](https://services.dev/docs/service/ask.md) | an `ask` | nothing | Free | `consent`, `organizer`, `authorize` |
| [An outside system](https://services.dev/docs/service/submit.md) | a `submit` | its fee passes through, at cost | Free | `pay`, `extend` |
| [The brand, on its own credential](https://services.dev/docs/people/brand-credentials.md) | `and: { brand: 'efin' }` | nothing | Every plan | `file` |
| [AI, with your review](https://services.dev/docs/people/sample.md) | `human: 'risky'`, or a `sample` that falls | nothing | Free · Launch with `human: { sample, floor }` | — |
| [Your staff](https://services.dev/docs/people/staff.md) | a role with no `pool` | your payroll | Free | — |
| [A Pool member](https://services.dev/docs/people/pool.md) | a role with a `pool` | pay per act | Launch | — |
| [A credentialed person](https://services.dev/docs/people/rules.md) | `rules`, and a role that holds the credential | pay per act; their own fee only where a Rules row sets `rail: 'member'` | Every plan · Launch with `Pool({...})` | `sign`, `prepare` |

api.lawyer's attorney sells `advise` on their own rail; apis.tax pays its signer $45 and $15 a jurisdiction an act. The Rules row decides, not the plan. [`check --who`](https://services.dev/docs/start/participants.md#who-does-each-step) prints this for one Service.

## Where a Pool's members come from

| From | One line | Roster · rules · name members see | Placement | Plan |
|---|---|---|---|---|
| [A Pool you rent](https://services.dev/docs/people/pool/share.md#import-a-pool-another-operator-runs) | `pool: 'gigs.expert/translators'` | the operator's, throughout | theirs, on each Task it fills | Launch |
| [Your own Pool](https://services.dev/docs/people/pool.md) | `Pool({...})`, at `/<pool>` on your brand | yours · yours · your brand | none | Launch |
| [An existing door](https://services.dev/docs/people/pool/door.md#use-an-existing-door) | `door: 'gigs.expert'` | the door's · yours · the door | the door's, on each Task it fills | Launch |
| [Your own door](https://services.dev/docs/people/pool/door.md) | `door: 'join.lingua.example'` | yours · yours · your door | none | Team |
| [Your Pool, sold](https://services.dev/docs/people/pool/share.md#export-your-pool) | `export` on your Pool | yours · yours, for every importer | yours, paid to you | Scale |

Every source keeps one [member charter](https://services.dev/docs/people/pool/door.md#the-member-charter) that no Pool, importer or door can weaken.

## Four brands

| Brand | Where a person comes in | Door |
|---|---|---|
| [lingua](https://services.dev/docs/examples/lingua.md) | nobody; AI delivers | none |
| [api.lawyer](https://services.dev/docs/examples/legal.md) | attorneys and patent practitioners, where the client is or anywhere | gigs.lawyer |
| [apis.tax](https://services.dev/docs/examples/tax.md) | a PTIN holder prepares, a CPA or enrolled agent signs, the taxpayer authorizes, and the brand e-files under its own EFIN | gigs.tax |
| [api.forsale](https://services.dev/docs/examples/sales.md) | no credential: a closer on every deal of $50,000 and up | closers.deals |