Getting your first workspace

By the end of this you will have an organisation, a workspace, a user account, and a bearer token for an AI client — and you will be signed in and looking at an empty workspace.

Where the first account comes from

An operator, on any installation that has left sign-up switched off — which is what every installation ships as. The first organisation, workspace, user, and token are created by a command run against the installation.

Onboarding a customer is deliberate, and this is the path for one — somebody with access to the installation creates the organisation and the first account, then hands over the address and the password.

An operator can switch self-service sign-up on instead (REQ-026). Where they have, the front page says so and links the form, and everything below is still how a second person gets an account: a sign-up creates a new organisation with one member, and there is no way to join one that already exists.

If somebody is already running md-platform for you, skip to Signing in and ask them for the address and your password.

Creating the first account

From the monorepo root, on the machine running the installation:

SEED_PASSWORD='a long passphrase' pnpm --filter @md-platform/core seed "RSU" "Knowledge" you@example.com "Your Name"

The four arguments are the organisation name, the workspace name, your email, and your display name. The password comes from the environment rather than from an argument, so it does not end up in shell history or in the process list.

It prints three identifiers and one secret:

organisation  01KZ…  RSU
workspace     01KZ…  Knowledge
user          01KZ…  you@example.com

Bearer token (shown once, store it now):
  mdp_…

The token is shown once. It is stored as a hash and cannot be recovered — a lost token is replaced, not retrieved. Keep it if you intend to connect a client over stdio; if your client speaks OAuth, you will not need it, and Connecting an AI client explains which you have.

Signing in

Go to /sign-in and use the email and password from above. There is no password reset flow, so if you lose it an operator sets a new one:

pnpm --filter @md-platform/core set-password you@example.com

That ends every session the account had. The usual reason to reset a password is that somebody should no longer have access, and sessions last thirty days — leaving them alive would mean the reset changed nothing for whoever already holds a cookie. Any MCP tokens the account issued keep working; revoke those separately if that is what you meant.

More workspaces

Once signed in, any member of an organisation can create another workspace from the web app, at /workspaces/new. It gets its own git repository and you become its first member.

An organisation holds many workspaces. It decides who may be a member and who administers what — it is never a scope for a content query. Every read and every write in md-platform belongs to exactly one workspace, and nothing you do returns documents from two.

What "done" looks like

You are signed in, /documents shows an empty workspace, and you have the workspace id from the seed output written down somewhere. Several operator commands take that id, and you can always list them again:

pnpm --filter @md-platform/core workspaces

Next: writing a document.