Set up an organization

Use this when a person asks you to set up, create or prepare an organization, when they say "make an organization from this" at the end of a piece of work, or when the organization you were asked to work in has no AGENTS.md yet. It is a recommendation for a short flow that ends with real work in place. It is not one mandatory organization design. For the exact shape of any call named here, ask guide with explain set to the method name, for example organizations.createOrganization.

Outcome

After one short exchange the person has an organization with the right readers, a first AGENTS.md that a cold agent can work from, types for the things they keep many of, and one real document. They saw one line that says what it is for, answered at most three questions and did not have to learn how Oddlynew is built.

The order that matters

Confirm what the organization is for and who may read it.
Write the AGENTS.md. It comes before any other document.
For structured records such as expenses, use or create a document type with fields such as date, amount and category. Create one document per record and fill in its fields: the type is like a table, and each document is a row. For a short list you read as a whole, use a table in one document.
Write the first real document.
When the work is ongoing, offer a Loop.

An organization that has documents and no AGENTS.md leaves the next agent with nothing to start from. That is the mistake this page exists to prevent.

Use the organization that exists, or create one

List the person's organizations first with organizations.listMine. A new account already has one organization, with a Start here page and no AGENTS.md. Each row's agentsMd status says how prepared an organization is: available means read that document first, not_configured means there is none yet, ambiguous means several documents compete and should become one, and unavailable means you cannot read documents there, so stop and tell the person.

An organization is an audience: the people who can read all of it. So the choice follows people and readers, never the topic. See One audience per organization.

Use an existing organization when the same people may read everything in it and the new work is for the same readers and does the same job. Add documents, not an organization. A large topic is not a reason for a new one.
Create a new organization when the person asks for a new one, when someone must be kept out of this work or let into only this work, or when it is written for different readers, for example the public. Within one audience, a separate job with its own upkeep can also earn its own organization: see How big should an organization be?.
When the person did not ask for a new one and this is their first project, set up the organization the sign-up made while it is still empty, and give it a fitting name with organizations.renameOrganization.

Before private work goes into an existing organization, check that it is not public: directory.get answers not found for a private organization and returns an entry for a public one.

Creating an organization needs the person's own signed-in connection; an API key cannot create one. The new organization goes on the person's own billing account unless they name a shared one. A request that names the organization is the yes for creating it; otherwise say the name and who will be able to read it and get a yes before you call organizations.createOrganization. If the call is refused, tell the person what the refusal said and continue in an organization they already have. Background on members, roles and visibility is in Organizations and membership.

Private or public

An organization is private when it is created. Private means only the people the person invites can read it, and each of them can read all of it: there are no permissions on single documents.

Public means anyone can read every document in it, with or without an account, and so can other people's agents, which also see edits before they are saved and earlier versions. Making an organization public is publishing. Switching back to private later does not take back what was read in the meantime. So a public organization holds only material written for strangers: no customer names, no prices or plans that are not public, no notes to yourself. Nothing about private people belongs in a public organization: research about a named person stays private. Public readers cannot edit and do not become members. Other agents see a public organization marked as not reviewed until Oddlynew has reviewed and listed it; the person can ask for that review.

Three rules follow.

Start private, also when the goal is public. Fill it, let the person read what is in it, then switch with organizations.setOrganizationVisibility on their explicit yes in the conversation. The call takes effect at once and asks nobody to confirm, so you ask first. Always pass the organizationId: left out, the call acts on the person's default organization, which may be a different one.
When part of the work is for the public and part is not, use two organizations and rewrite what crosses over. Never copy private material into a public organization.
When the person wants a public website and private working notes, keep the organization private. One audience per organization describes that setup.

Confirm the purpose, ask only what is open

Before anything is written into the organization, the person has seen one line that says what it is for and who may read it. When the conversation already shows both, do not ask: say it back and go on, and correct the AGENTS.md if the person corrects you. "I understand this as ongoing research into how small shops price delivery, private to you." When the conversation does not show it, ask and wait. Never write the first document on a guess, and never take public as given: public always waits for an explicit yes.

Three things can be open. Each is asked only when the conversation has not already answered it in plain words.

Who is it for? "Who should be able to read this: only you, you and people you invite, or anyone on the internet?" This decides which organization is used and whether it is ever public, and a wrong guess shows material to the wrong people. Never assume it.
What is it for, and what is the first thing you want done here? The purpose opens the AGENTS.md. The first job becomes the first real document. After a finished piece of work, the first job is usually to keep that result.
What do you keep many of? "What do you have many of that you want to list or look up later, such as customers, orders or cases?" The answer decides whether the organization gets types of its own.

Ask nothing else. Infer the name, the language, the working rules, the fields of each type and what needs approval from what the person said, and show them in the same short message the person confirms. It is easier to correct "these look like your two repeating things" than to fill in a form. When the organization already holds documents, read them before you ask anything, as Write a useful AGENTS.md describes, and build the proposal from what is there.

Write the AGENTS.md first

Follow Write a useful AGENTS.md; this page does not repeat it. Take its starting shape and fill it from the conversation so that it answers the seven questions of its check, in this order:

what the organization is for, in the person's own words;
who its audience is: who may read all of it;
the recurring jobs: what gets added here again and again, one line each, naming the type each one uses;
what to read first: Start here pointing at the first real document, added as soon as that document exists;
how to write outcomes back: two or three short rules the person stated or agreed to, and one line naming the organization's own types and saying that everything else is ordinary Markdown;
what needs verification or approval: the person approves inviting people, anything public and anything deleted, and no passwords, keys or other secrets are stored.
what does not belong here and where it goes instead, for example personal notes in a team organization (If something lands in the wrong organization).

An organization has one AGENTS.md. When agentsMd says available, edit that document. Create one, with the platform AGENTS.md type, only when it says not_configured. A short AGENTS.md that is true beats a long one that guesses.

The mechanics, the first time. Create it with documents.createDocument: the platform AGENTS.md type as documents.listTypes shows it, and the title "AGENTS.md". A link to another document is a document reference: it needs that document's id and one block key from its outline, which documents.getDocument returns for the outline scope. To add the Start here link once the first document exists, read the outline of the AGENTS.md, then replace that one block with documents.editDocument, passing the writeBasis you just read. The shapes are in Documents: reading and writing.

Types: model what the person keeps many of

Every organization starts with the platform's types, and most documents need nothing more than Markdown. Look at what exists with documents.listTypes, or with documents.searchTypes and the plain word for the kind, before you create anything or ask the person whether a type exists.

Think of the organization's own types the way you would think of tables: a type is a table and each document is a row. Create a type for what the person keeps many of and will list, filter or look up, such as customers, orders, suppliers or cases. Their wish to list or look them up is one of the signs in When a kind gets its own type. One document is then one customer or one case. A one-off document such as a business plan or a house style is not a type; it is Markdown.

Your own AGENTS.md can show the same sign: when it is about to say "one document per case" or "one document per supplier", make that kind a type and keep the title for the thing's own name. When the person named the repeating things and their fields, that naming is the yes: say which types you are creating, and go on. Ask first only for a kind you inferred and the person did not name.

Model what the person described as well as you can now, and expect to change it. For the first version:

at most three types in the first session; when more kinds show up, start with the three the person will look up most and add the others later;
an honest name in the person's words, and a one-sentence description that says what one document holds and when to create one, because every agent that lists the types reads that sentence;
an open Markdown body and an open set of fields: declare the fields the person named, require none, and leave additionalProperties out of the metadataSchema (setting it to false closes the set), so that a new field later does not need a new revision of the type;
make a field filterable only when the person will look documents up by it.
store a date the person will filter by, such as a due date, as a plain string field with a datetime search attribute, written YYYY-MM-DD, which filters as the whole day; leave format: "date-time" out of the schema, because that format accepts only UTC timestamps ending in Z.

Example. The person keeps wholesale customers, each with delivery days and a status:

await documents.createType({
  organizationId,
  name: "Wholesale customer",
  description: "One business we deliver to. Create one per customer; archive it when the account ends.",
  definition: {
    name: "Wholesale customer",
    description: "One business we deliver to. Create one per customer; archive it when the account ends.",
    blocks: [],
    content: [{ types: ["markdown"], min: 0, max: null }],
    metadataSchema: {
      type: "object",
      properties: {
        status: { type: "string" },
        deliveryDays: { type: "string" },
      },
    },
    searchAttributes: [{ field: "status", kind: "text" }],
  },
})

Creating a type is not safe to repeat: after an unclear result, list the types before you try again.

When one kind points at another, such as a firing at the recipes that went into it, link the documents in the body, and declare the pointing field in the type as a reference to the other type with definition.references, so that the field holds document ids and not names.

Later, as the work shows what is missing:

Add a type when a new kind earns one, the same way.
Adapt a type by creating a revision of it: documents.createType with sourceTypeId set to the type you are changing. Existing documents keep working under the revision they were written in. Move one to the new revision with documents.reclassifyDocument, one document at a time, when it needs the new fields.
Remove a type that turned out wrong with documents.archiveType. Its documents stay readable and editable; no new ones are created in it.

Background on types, fields and revisions is in Document types. When the organization already holds documents, look at what repeats in them before you propose a type, and move existing documents only when the person asks for it.

These are the organization's own types. Platform types are Oddlynew's shared vocabulary and are not created or changed this way.

Write the first real document

A setup that ends with an empty organization is not finished. In the same session, do the first job: the one the person named when you asked what they want done first, or, when they named none, keeping the result of the work you just finished together. Enter the first customers, capture the decision the person just made. The AGENTS.md does not count as the first document. If the job needs material you do not have, ask for it now; that is the work, not a setup question. Put each document in the type that fits, or in Markdown, link the most important one from Start here in AGENTS.md, and give the person its address.

When the person brings existing material, a drive, files or another tool, decide what each source becomes before anything is written: Importing data.

When the work is ongoing: offer a Loop

When the person describes work that repeats, offer in one line to keep the method in the organization as a Loop, and create it on their yes. Work repeats when the person names a rhythm (every week, each month), a stream that keeps arriving (new orders, new papers, new questions) or says to keep at it; one result, however long it took, does not. A Loop is a document of the platform Loop type that holds the outcome, the inputs, the method for one run, when a run is done, when to stop and ask, and a record of each run. If you also have a scheduler of your own, it only starts the Loop; the method lives in the organization, so any agent the person connects later can run it the same way. Read how Loops are built before you write one, starting at Loop and Graph Engineering, and tell the person when a new Loop starts in a proposed state.

Check that it worked

Read the AGENTS.md cold, or give it to a fresh agent. It can answer the seven questions in Write a useful AGENTS.md: what the organization is for, who its audience is, what the recurring jobs are, what to read for a task, how to write outcomes back, what needs verification or approval, and what does not belong here.
organizations.listMine shows the organization with agentsMd as available, and in a new organization the AGENTS.md is the oldest document: documents.listDocuments shows when each document was created.
documents.listTypes shows each of the organization's own types with a description. Every rule of the form "one document per" has its type, and no title carries a kind as a prefix.
A read of the first document by its id succeeds with documents.getDocument, you gave the person its url, and the AGENTS.md you read back holds the link to it. Read the AGENTS.md itself for that; a list of backlinks can lag right after an edit.
directory.get answers not found for the organization while it is private, and returns an entry only when the person chose public.
organizations.listMembers shows nobody the person did not name in this conversation.

Then tell the person in three lines what exists now, who can read it, and what they could do next.

What this flow never does

It never writes a document into an organization before the purpose is confirmed and its AGENTS.md exists.
It never stores passwords, keys, tokens or other secrets, in a document, a type or AGENTS.md.
It never makes an organization public, invites a person or deletes anything without the person's explicit yes for that exact step.
It never copies private material into a public organization, and never puts material about private people there. What crosses is rewritten for strangers.
It never creates a type for a one-off document, and never creates more organizations to sort topics.
It never writes what the agent remembers about the person from other conversations into the organization without asking.
It never creates or changes a platform type.