Create the tenant repository

Everything a tenant runs is defined in one folder, kept in git: the tenant’s settings, its CRM field map, and its motions. Motions doesn’t edit this folder; you change it, test it, and push it. The app shows what you pushed.

What’s in it

• tenant.yaml the tenant’s id, name, time zone and fixture mode
• crm.yaml which CRM, read-only or not, and the field map
• crm-seed.json records for the built-in test CRM (test CRM only)
• Directoryfixtures/

  • Directorysources/ recorded answers for the built-in sources

    • …
• Directorymotions/

  • Directoryweekly/ one folder per motion

    • motion.yaml
    • rules.yaml
    • Directorysteps/

      • …
    • Directorylib/

      • …
    • Directorytests/

      • …
• Directorysources/ your own data sources, if any

  • …
• package.json
• tsconfig.json

Every file is described in Tenant files and motion.yaml.

Create it

1. Make the folder and start a git repository in it.

   mkdir v360 && cd v360 && git init

2. Add package.json and tsconfig.json. The command line tool is @motionskit/cli; steps import @motionskit/sdk. zod is for typed step output and for custom sources.

   package.json

   {
     "name": "orbita",
     "private": true,
     "type": "module",
     "scripts": {
       "check": "motions check",
       "test": "motions test",
       "typecheck": "tsc -p .",
       "push": "motions push"
     },
     "devDependencies": {
       "@motionskit/cli": "^0.1.0",
       "@motionskit/sdk": "^0.1.0",
       "typescript": "^5.9.3",
       "vitest": "^5.1.0",
       "zod": "^4.6.7"
     }
   }

   tsconfig.json

   {
     "compilerOptions": {
       "target": "ES2022",
       "module": "ESNext",
       "moduleResolution": "Bundler",
       "allowImportingTsExtensions": true,
       "strict": true,
       "noEmit": true,
       "skipLibCheck": true
     },
     "include": ["motions", "sources", ".motions/*.d.ts"]
   }

   Add a .gitignore with node_modules, then install:

   npm install

   Not on npm yet

   The @motionskit packages haven’t had their first release. Until they do, npm install can’t find them; ask Pruma for the packages.

3. Add tenant.yaml. id must be your tenant’s id exactly, as it appears in the app’s address after /t/. timezone is the zone your calendar and deadlines are in.

   tenant.yaml

   id: orbita
   title: Órbita Software
   timezone: America/Sao_Paulo
   # Built-in sources answer from fixtures/sources/*.json, so nothing here needs a provider key.
   sources: { fixtures: true }

   Leave sources: { fixtures: true } on while you build: the built-in sources then answer from fixtures/sources/*.json and cost nothing. You turn it off when you go live.

4. Add crm.yaml. Start with the built-in test CRM, as in the Quickstart, or go straight to Connect HubSpot.

5. Create an API token for yourself: Settings → API tokens → New API token. Only owners and admins see this page.

   • Handle: your own handle, so what you push is recorded as yours.
   • Role: approver is enough to push motions and open batches. Choose admin if you’ll script member or settings changes too.
   • Expires in: a number of days, or blank for a token that doesn’t expire.

   Copy the token when it appears: the app never shows it again.

6. Point the tool at your tenant. The command line tool reads two environment variables. MOTIONS_URL is the address you open the app at, without any path.

   export MOTIONS_URL=https://motions.pruma.tech
   export MOTIONS_TOKEN=   # paste your API token after the =

   Put these in your shell profile or a password manager’s shell integration, not in a file inside the repository.

7. Check and push.

   npx motions check
   npx motions push

Never commit the token

An API token acts as you. Keep it out of the repository, out of tenant.yaml, and out of anything you paste into an AI assistant’s context. If it leaks, delete it in Settings → API tokens and create another.

What a push does

motions push sends the whole folder, in this order:

1. The tenant’s settings: title, timezone, the CRM connection and field map from crm.yaml, and the fixture switch with its fixtures.
2. The test CRM’s records, from crm-seed.json, but only into an empty test CRM. motions push --reseed replaces whatever is there.
3. Your custom sources, from sources/.
4. Each motion, as a version. A version is identified by its content, so pushing an unchanged motion changes nothing.

Without --live, each new version is a draft: you can open a batch on it, compare it with the live one, and make it live in the app. With --live, it becomes live straight away. The tool prints a link to each version.

Pushing crm.yaml can change your CRM connection

The push sets the connection to whatever crm.yaml says. If system changes, say from hubspot back to memory, the stored HubSpot token is forgotten and someone has to paste it again. Keep crm.yaml stable once HubSpot is connected.

The scaffold

npx motions init <folder> writes a starting tenant with an example motion and a GitHub workflow. It still names an approver owner, which matches no one, and its workflow uses this repo’s private push action, so copying the Quickstart files is the better start.