Skip to content

Concepts

GaugeWright has a small, consistent vocabulary. Learn a handful of ideas here and the rest of the product follows. This page is the five-minute mental model; for precise one-line definitions of every term, see the Glossary.

The one counterintuitive truth, up front

Orchestration is local; inference is not. The workbench runs on your machine, but the agent's reasoning is performed by the third-party LLM provider you configure — your prompts and the in-scope context are sent to that provider over the network. There is no local model. See Where your data goes before you trust anything sensitive to a run.

What you can use today

GaugeWright ships in increments, so the docs are honest about what is live versus designed. Throughout, capability claims carry a badge that defers to the single status table in Roadmap & status:

  • Available — in the product you can download today
  • Built — implemented and tested in code, not yet operationally deployed
  • Planned — committed, not yet built
  • Not implemented — absent today

Today, only the local desktop workbench — build a method, run it on local context, review the result — is Available. Cross-party packaging, attested compute, enterprise identity, and hosted/embedded agents are Built or Planned. The concepts below describe the whole model; the badges tell you which parts are live.

The shape of the product

You build an agent once, then run it on real work — without your method or the data leaking. Three nouns carry that idea:

  • An archetype is the reusable agent definition — its instructions, skills, and tools. It lives in your library, not in a project, and you build and refine it in an edit chat. Concretely it is the Pi-native surface in the archetype's repo: .pi/SYSTEM.md (system prompt), AGENTS.md (instructions), .pi/skills/, .pi/extensions/, plus .agent-config.json (model selection and the declared protection posture). Available
  • A placement is an archetype installed onto a project — the durable deployment you actually do work with. Its identity is archetype · project, so the method's lineage is always visible. One archetype can be placed on many projects; one project can hold many placements. Available

  • A chat is a durable line of conversation. Its kind is fixed by what it is rooted on — there is no edit/use toggle: Available

    Rooted on an archetype. Its subject is the method; its output is a published version. This is the only place the method is authored.

    Rooted on a placement. Its subject is the project's work; it consumes the method read-only and cannot change it.

Where work lives

  • A project is a trust and data boundary — a body of work plus the parties who may see it (personal, client, expert, auditor…). Two bodies of work that must stay apart are two projects, and that non-mixing is the boundary. A project holds context, placements, and runs; it is not a folder or a git repo. Available

Three load-bearing words: resource, handle, boundary

These three turn the nouns above into something protectable. They are the heart of how GaugeWright protects your work.

  • A resource is any protected thing the system records or moves: a method, a context, or a derived output. Method and context are both resources — neither is privileged.
  • A handle is the reference by which a resource is addressed. A handle is not access. Holding or transporting a handle conveys no read of the payload; reading the data requires a separate, explicit grant evaluated at the boundary. Available
  • A boundary is the protected execution context where resources meet and run, and the single point where egress is enforced. Every channel out — output, tool call, log, export — routes through it. A run inside the boundary has no ambient power beyond what it was admitted to do.

How work happens

  • A run is one episode of agent work — one per chat turn — performed inside the boundary. It reads/edits/runs in a sandboxed worktree, streams progress, and stops at the end of the turn. It consumes only the work it was admitted to do. Available
  • Generating an output is not releasing it. Outputs are held until reviewed and explicitly released to authorized stakeholders. The full review/release lifecycle is Built; the local keep-or-reject diff is Available.
  • An engagement is the method-owner ↔ context-owner relationship a chat works under — the unit at which taint is tracked so an output's conservative provenance is the owners of everything that chat read. "Engagement" no longer names a mode (ADR 0045 retired the autonomous-vs-interactive axis); what survives is chat-scoped taint. Available (as chat-scoped taint)

Working with others

  • A workstream is a shared line of work that multiple chats greedily auto-sync into. The single-placement sync/promote loop is live; cross-authority and real-time multi-user sync are a later (M2) axis. Available

  • Federation moves things between parties — across machines or authorities — always with the source's permission and the target's admission. Available

    What \"Available\" means for federation today

    Federation is exercised in CI over a loopback + NAT-isolated harness (cert-pinned TLS, blind relay) — the protocol and its invariants are implemented and tested. It is not yet wired into a turnkey, real-world cross-machine deployment; standing up two machines is still a manual recipe. Treat it as proven in code, not as a one-click feature.

What this model does not give you today

Honest limits, so you don't over-trust a concept:

  • Local placement does not hide your method from the context owner. When you are both the host and the context owner (the MVP desktop case), the method and the model endpoint are inside the trusted set — secrecy from yourself is not achievable, only obfuscation. Host-blind method secrecy needs attested compute (attestation), which is verifier Built / live Planned.
  • The third-party LLM provider sees plaintext. Removing the provider from the trust boundary (confidential inference) is Planned. Until then, use a provider you have contracted, or keep sensitive data out of runs.
  • Kernel-enforced method isolation is Linux/macOS only. The Windows sandbox is Planned; on Windows the edit/work write-gate is not yet kernel-enforced.
Who can see plaintext, plainly?

The operating host of the boundary reads plaintext by necessity — it runs the work — and so does the LLM provider you configured. Other parties in a project are walled off by resource ownership, taint, and conjunctive egress — but those are structural guarantees about parties, not about the host or the model. Full detail: Where your data goes.

Next