Metadata-Version: 2.4
Name: protocolcity
Version: 0.1.4
Summary: ProtocolCity BluePrint — found a city, serve the Office (cabinets home; map annex)
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Provides-Extra: engines
Requires-Dist: protocolcity-worklane; extra == "engines"
Requires-Dist: protocolcity-workforce; extra == "engines"

# 🏙️ Protocol City

**Protocol City** is a governed digital city where humans and AI agents build
products together — and the products it ships exist to give everyone else the
same leverage.

The founding line, written before any of the tooling existed, still holds:

> Every bot is a worker, every `.md` is a law, and every contributor becomes a
> citizen.

One operator runs a workforce of AI agents — Claude, Grok, Cursor, Codex —
across multiple products, from one machine. No agent framework, no SaaS
dependency, no vendor lock. Coordination happens through a protocol: files,
tickets, and signed work — durable, auditable, human-readable.

## The city

The metaphor is not decoration; every term maps to something real and running.

| In the city | What it means | Concretely, today |
|---|---|---|
| **The city** | The whole governed system: every product, agent, human, and rule under one charter | Everything under `~/Developer`, the `protocolcity` GitHub org, this brand |
| **City Hall** | Where the city is governed — charter, records, product registry, brand. No product code lives here. One of three **rooms** citizens operate | **This repo** (BluePrint's own contribution — no engine brand) |
| **Neighborhoods** | The places where work happens. Each is independent — its own repo, its own local law, its own **ledger** of work — but protocol-compliant at the city level | tradeOS, TP, socials… (see table below) |
| **Desk** | The room where every job is filed, claimed, and signed. No work moves by chat or memory — it moves by ticket. | Powered by **WorkLane** (TP internally) |
| **Dispatch** | The room where the workforce is scheduled and sent out — identities, shifts, who works what | Powered by **WorkForce** (orchestrator; extraction gated) |
| **The workforce** | AI agents employed by the city — any vendor. Each has a registered identity, a job description, a schedule, and signs everything it does | 5 lanes + report jobs on launchd, signing into TP |
| **Citizens** | The humans. Bots execute; humans govern — citizens hold the taste, the gates, and the final word | The founder today; the v1 role ladder (visitor → resident → builder → architect → citizen) is the future community model |
| **Laws** | The rules — always written down, always readable, one owner per rule. Documentation is the interface: if it isn't in an `.md`, it isn't law | Every `AGENTS.md`, `PROCESS.md`, charter, and ADR in the city |

**One metaphor family.** The city is the only lens — rooms, desk, workforce,
neighborhoods, citizens, laws. Where you see *store* (a ticket store, a store
slug), it's **developer** vocabulary for the data-store artifact; **citizens**
say **ledger** ("each neighborhood keeps a ledger at the Desk"). Never a
second retail metaphor; in prose the image is always the desk.

**Two audiences, one name each.** Citizens think in **rooms** — City Hall,
Dispatch, Desk. No instruction a citizen must follow may require an
engine name; engine brands appear only as "powered by" credits. Developers
think in **engines** — WorkLane and WorkForce are the GitHub/PyPI artifacts,
each carrying its room when sold standalone. **Wayfinding:** door label ==
destination header == room name, always (engines are never navigation targets).

**Three registers, one owner each.** So the city stays legible to a newcomer,
every term speaks in exactly one register. *Operational* words — the ones you
must know to run the city (`worker`, `contract`, `roster`, `ticket`,
`dashboard`) — are plain industry terms, owned by the
[Charter](docs/CHARTER.md) reserved-words table; a filename must pass the same
bar (say what it is from the name alone). *Civic-metaphor* words (city,
neighborhood, citizen, city hall, desk) are **brand voice only** — fine in this
glossary and on surface subtitles, never required to read an operational doc,
and **never a filename**. *Boundary artifacts* (marketing, exports, public
READMEs) speak plain industry terms always — the reader hasn't adopted the world
yet. Concretely here, the three **dashboards** are ProtocolCity's own surfaces —
**Projects** (City Hall), **Workers** (Dispatch), **Tickets** (Desk) —
plain function words in-city; room name is the header; engine brand is the
powered-by credit (or the product title when installed standalone).

A **neighborhood** is the unit of independence: it can be a live trading
system, a content operation, or a dormant experiment, and the city doesn't
care — as long as it keeps the protocol. Keeping the protocol means three
things: its law is written (`AGENTS.md`), its work is ticketed (filed at the
Desk), and its workers sign what they do.

### Neighborhoods today

| Neighborhood | What happens there | Work orders | Status |
|---|---|---|---|
| **tradeOS** | Trading alerts, journal, broker automation | `ts-*` / legacy `t-*` | Live — real money, launchd services, agent lanes |
| **worklane** | Desk engine (public brand **WorkLane**; package dir still `ticketingprotocol/`) | `wl-*` / legacy `tp-*` | Live — own backlog; store slug `worklane` (tp-207) |
| **workforce** | Employment / Roster engine (public brand **WorkForce**) | `wf-*` | Live — daemon + :8797 Roster |
| **socials** | Build-in-public content operation | `so-*` | Drafting — posting is citizen-only |
| **Protocol City** (City Hall) | Governance, registry, research | `pc-*` | Active — founder-present sessions, suite workers |

Retired neighborhoods keep their records: health_ai (v1 empty scaffold) lives
in [`_archive/v1-city/health_ai/`](_archive/v1-city/health_ai/) — its tool
names (`create_neighborhood`, `check_doc_compliance`) survive as the seed of
the future scaffold/lint tooling.

## Founding principles

Carried forward from the [v1 mission](docs/mission.md), proven by the running system:

1. **Bots execute, humans govern.** Agents work autonomously inside their
   lanes; anything public-facing, irreversible, or matter-of-taste is
   citizen-gated.
2. **Every action is signed.** Work orders, comments, and commits carry the
   identity that made them — a tamper-evident history of who did what.
3. **Documentation is the interface.** The city is legible to humans and
   agents through the same files. New agent, new vendor, new person: read the
   law, start working.
4. **The protocol is open; the services are premium.** The coordination layer
   ships free and vendor-neutral (WorkLane, Apache-2.0). Products built on it
   can be businesses.
5. **Every folder has a purpose.** Strict file hygiene isn't tidiness — it's
   what makes a city navigable by anyone, including a graph view.

## The schema

Underneath the metaphor, every product slots into one of three layers:

| Layer | Owns | In the city (room) | Product (engine) |
|---|---|---|---|
| **Store** | The work — tickets, claims, signed authors, audit trail | **Desk** | [WorkLane](https://github.com/protocolcity/ProtocolCity-WorkLane) |
| **Orchestrator** | The workers — identities, schedules, dispatch, budgets | **Dispatch** | **WorkForce** *(extraction gated; pattern runs today as launchd lanes/jobs)* |
| **Workplace** | The code the workers act on | A neighborhood | tradeOS *(and every future app)* |

The orchestrator — who works, when, with what authority — is the layer the
industry keeps burying inside single-vendor runtimes. The case for extracting
it as a neutral product:
[docs/research/orchestrator-layer-2026-07.md](docs/research/orchestrator-layer-2026-07.md).

## Products

*(This is the **brand** registry — what the products are. The **operational**
registry — folders, repos, gates, status — is city law at the workspace root;
O-5 adjudication, 2026-07-14. Two-audience rule ratified [pc-37](docs/research/two-audience-naming-audit-2026-07.md).)*

```
ProtocolCity (the brand / the protocol)
└── BluePrint — the suite's shippable form: "install this, it founds your city"
    ├── owns    → City Hall     (the join room — BluePrint's own contribution)
    ├── depends → WorkLane  → Desk
    ├── depends → WorkForce → Dispatch
    └── later   → connector (internal; public brand TBD) — connect You to a hosted city
```

**BluePrint is the roof, not a third pillar** — Charter + templates + found +
City Hall. Cut the roof off and the engines still hold their rooms. Adoption
ladder (optional rungs): **WorkLane alone** (shared agent queue, the wedge) →
**+ WorkForce** (scheduled shifts) → **+ BluePrint** (multi-project operating
model + City Hall). Roofs go on last. A later rung — **connector** (pc-220) —
hosts the city on a network and connects a citizen; tabled until WorkLane has
flipped and multi-citizen identity is ready.

- **BluePrint** — the suite kit that founds a city: law, templates, City Hall.
  Depends on WorkLane and WorkForce; never the reverse.
- **WorkLane** — the Desk engine (Apache-2.0). GitHub/PyPI-facing;
  carries the Desk room when sold standalone.
- **WorkForce** — the Dispatch engine (orchestrator layer; public brand).
  Identity, schedule, dispatch, budget, tamper-evident work history.
  Extraction gated; the pattern currently runs as nine production lanes/jobs
  on one machine.
- **connector** *(internal codename; public brand TBD — pc-220)* — fourth
  product carve: host a city folder on the network; connect You (identity,
  MCP/`tk` hands, room doors). Package intent `protocolcity-connector`.
  **Tabled** — not in the v1 ship cut; engines stay one-laptop-trust until
  this lands. Carve: join UX + client connect live here; port auth stays on
  each engine.
- **Horizon** (names only, no engines yet — pc-230 list ratified 2026-07-17;
  PyPI reservation **tabled**): **Library** · **Inspector** · **Meter** ·
  **Agency** · **Post** · **Archive** · **Court**. Thesis and package
  intents: city root `AGENTS.md` horizon table + 
  [product-horizon research](docs/research/product-horizon-2026-07.md).
  Suite mast shows them as planned chips; do not build or reserve until
  un-tabled.
- **tradeOS** — trading alerts, journal, and broker automation. Private
  source; public face is a release shell repo. A **workplace** neighborhood,
  not a room of the suite.

**Rooms are not products; dashboards are not products.** Citizens operate three
**rooms** — City Hall, Dispatch, Desk. The three **dashboard** chrome
labels — **Projects**, **Workers**, **Tickets** — are plain function words on
those rooms, not a second brand set. In-city, the suite brand fronts the suite;
an engine's brand fronts it only when installed standalone
(`WorkLane — Tickets`). O-5 scopes stay intact (2026-07-14 / pc-37).

## Repo map

| Path | What it is |
|---|---|
| [`docs/CHARTER.md`](docs/CHARTER.md) | **The Charter** — the host-neutral spec (definitions, levels of law, compliance test, founding path); ships publicly as **ProtocolCity-BluePrint** |
| [`AGENTS.md`](AGENTS.md) | Canonical agent instructions for this repo |
| [`docs/mission.md`](docs/mission.md) · [`docs/manifesto.md`](docs/manifesto.md) | The brand story |
| [`docs/index.md`](docs/index.md) | Map of the docs |
| [`docs/policy/`](docs/policy/) | Governance — charter, licensing, security, conduct |
| [`docs/research/`](docs/research/) | Org-level research and product decisions |
| [`docs/citizens/`](docs/citizens/) | Citizen onboarding — the community model |
| [`_archive/v1-city/`](_archive/v1-city/) | The v1 build (April 2026) — the hand-built prototype of all of this |

## Origin

Protocol City started in April 2026 as a hand-built, file-based operating
system where bots proposed and a human approved — workorders as markdown,
an audit hashlog updated by shell script, a written agreement between one
human and one bot. Before any of the tooling existed, v1 had already named
the concepts: work orders, trusted agents, neighborhood constitutions.

The tooling caught up. The Desk became a real ticket server; the
hashlog became signed, tamper-evident history; the constitution became
per-repo law that four different vendors' agents obey. That v1 is preserved
in [`_archive/v1-city/`](_archive/v1-city/), because the thesis never
changed: **a single operator can run infrastructure, automation,
documentation, and governance by pairing with AI and keeping strict file
hygiene.** The city is the proof. The products are the invitation.
