Bases — the Data surface

Open this the moment a task involves a base: designing a schema, reading or writing records, linking entities, storing files, wiring an integration, or building an agent-facing toolset. It is the complete concept map for the Data surface; the sibling files carry the field-level grammar.

A base is an org-level data container — the system of record behind your hubs. Hubs hold conversations; bases hold the structured data those conversations act on. They are separate entities with separate commands: wayai publish promotes a hub, wayai bases promote promotes a base, and wayai pull/wayai push route by workspace subtree (hubs/ vs bases/). Never substitute one for the other.

The object model

Organization                       ← account boundary; base tokens
└── Base (production | preview)    ← one per app, domain, or tenant
    ├── CONFIG — edit in a PREVIEW, ship with PROMOTE (human-run):
    │     record types (+ their external sources) · relationship types
    │     · triggers · inbound webhooks · Actions · toolsets · seed fixture definitions
    │     · file types (config too, but NOT in the config-as-code subtree — see files.md)
    └── DATA — read/write on ANY base, production included:
          records · relationships · files · attachments · batch writes
          (seed apply/reset/clear and seed leases run only on previews)

The one rule that routes every command: config writes are rejected on a production base — make them in a preview (wayai bases create-preview), then have the user run wayai bases promote. Ordinary data writes work anywhere; seed-fixture and seed-lease operations are preview-only. If a write unexpectedly fails with a preview/403 error, check whether it is config or eval-state work aimed at production.

Every primitive, one line each

Two schema→instance pairs anchor the model: record type → record and relationship type → relationship. Files repeat the pattern (file type → file).

Identity rules. Config slugs are permanent ids — the id of a base, record type, relationship type, Action, and toolset is its identity and is immutable. There is no rename: to "rename" one you create a new entity and migrate its data. Choose clear, stable, lowercase-slug ids up front (patients, treated_by). Display names and descriptions stay editable. Always set external_id on records that have a natural key — retries and re-imports then upsert instead of duplicating.

Consistency & limits. Single-record gets and eligible active-record list queries reflect writes immediately; sql, search, and filters on the built-in created_at/updated_at timestamps written without a timezone offset may lag a write by a moment. Record/relationship JSON is capped at ~1 MiB — large or binary content belongs in Files.

Agent guidelines for base work

• Schema work (record types, relationship types, file types, inbound webhooks, triggers, Actions, toolsets, seed fixtures) only happens in preview bases. Create or select one before changing schema.
• Promotion is human-only. When the schema is ready, surface the exact wayai bases promote command and wait for the user to run it. Recommend --dry-run first.
• Base tokens are shown only once on creation. Tell the user to copy and store one before doing anything else.
• Once the config spans more than a couple of entities, prefer config-as-code (wayai pull bases/<base> / wayai push bases/<base>) over one-off commands, so changes are reviewable files. See Base config as code, environments, and seed fixtures.
• Never auto-commit. Show git diff and wait for approval.
• wayai <command> --help is the authoritative flag list at runtime. If a command, flag, or URL appears in neither these references nor --help, assume it does not exist — never guess one.

Task → reference map

Getting a base for the first time

You are already authenticated — one wayai login covers hubs and bases, and wayai status --json reports it. There is no second CLI, no second login, and no second workspace.

wayai bases create <base-id> --name "<Display Name>" [--tags a,b] [--timezone <IANA>]

--environment production is the default, and what your plan bounds is capacity — records, operations, import rows — not which environment you may create.

--tags names the organization's own tags — the same list hubs and credentials draw from, created under Settings → Organization → Tags. A name that is not in that list is rejected rather than created, so tags mean the same thing wherever they appear.

Create production first for anything you intend to keep. A base's environment cannot be changed while it exists, and there is no step that links an origin-less preview up to production later — so the durable name should be claimed by the production base at creation; then take a linked preview off it for config work and promote from there. (The slug is recoverable if you get this wrong, but only by destroying the preview's data and starting the base over on the same id — see below.)

wayai bases create <base-id> --name "<Display Name>"          # production — claims the durable id
wayai bases create-preview <base-id> --name "<Display Name> (dev)"
# …edit record types, triggers, toolsets in the preview…
wayai bases promote <base-id> --from <preview-id>

Create a base directly as a preview only when it is ephemeral — an eval run or a throwaway sandbox under a derived, unique id:

wayai bases create <eval-run-id> --name "Eval run" --environment preview

A preview created that way has no production origin, so it cannot be promoted directly, and environment cannot be changed on a base that exists. That is the trap to avoid for a durable base: there is no later step that links it up. The way back is to destroy the preview's data — delete it with purge — and, once that deletion completes, create the same id again as production: a freed id is a blank slate and may be created in either environment. Nothing carries over, so it is a fresh start on the slug rather than a promotion; see Base config as code, environments, and seed fixtures.

Then define the first record type in a preview, write test records, and iterate:

wayai bases create-preview <base-id> --name dev
wayai record-types upsert <slug> --base <base-id>--dev --name "<Display Name>" --schema @schema.json
wayai records upsert <slug> --base <base-id>--dev --data '{...}'

Set WAYAI_BASE=<id> in the shell to stop passing --base on every command. wayai use bases/<id> is not an alternative — the worktree scope is a routing tripwire for pull/push only, and every other command still resolves its target from --base or WAYAI_BASE and errors out without one.

When the schema is right, surface the promotion for the user to run:

wayai bases promote <base-id> --from <base-id>--dev --dry-run

Connecting a hub to a base

Two paths work today, and neither is the same thing as the hub's own config:

• Agent tools — build a toolset (Toolsets and Actions (the MCP factory)), mint a toolset-bound rec_ token, and add it to the hub as an ordinary MCP Server connection (Streamable HTTP, Bearer Token) pointed at https://data-mcp.wayai.pro/t/<slug>/mcp. The agent then sees your domain tools (book_appointment, list_invoices), not generic data operations. See connections.md in the WayAI skill for the connection mechanics.
• Eval seeding — an eval set or journey names a fixture: and a target_base:, and the hub's seed connection supplies the API origin and a write:seeds token. See evals.md in the WayAI skill.

A hub's own knowledge/skill resources are a different surface and stay hub-local — they are not base files. See resources.md in the WayAI skill.